Azure Communication Call Automation Service client library for Java - version 1.3.0

Article
11/23/2024

This package contains a Java SDK for Azure Communication Call Automation Service.

Source code | Package (Maven) | API reference documentation | Product documentation

Getting started

Prerequisites

An Azure account with an active subscription. Create an account for free.
Java Development Kit (JDK) version 8 or above.
Apache Maven.
A deployed Communication Services resource. You can use the Azure Portal or the Azure PowerShell to set it up.

Include the package

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-callautomation</artifactId>
    <version>1.1.0</version>
</dependency>

Key concepts

This is the restart of Call Automation Service. It is renamed to Call Automation service and being more intuitive to use.

CallAutomationClient provides the functionality to make call, answer/reject incoming call and redirect a call.

CallConnection provides the functionality to perform actions in an established call connection such as adding participants and terminate the call.

CallMedia introduces media related functionalities into the call.

CallRecording provides the functionality of recording the call.

CallAutomationEventParser provides the functionality to handle events from the ACS resource.

Examples

Handle Mid-Connection events with CallAutomation's EventProcessor

To easily handle mid-connection events, Call Automation's SDK provides easier way to handle these events. Take a look at CallAutomationEventProcessor. This will ensure correlation between call and events more easily.

@RestController
public class ActionController {
    // Controller implementation...

    @RequestMapping(value = "/api/events", method = POST)
    public ResponseEntity<?> handleCallEvents(@RequestBody String requestBody) {
        try {
            CallAutomationAsyncClient client = getCallAutomationAsyncClient();
            client.getEventProcessor().processEvents(requestBody);

            return new ResponseEntity<>(HttpStatus.OK);
        } catch (Exception e) {
            return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
        }
    }
}

processEvents is required for EventProcessor to work. After event is being consumed by EventProcessor, you can start using its feature.

See below for example: where you are making a call with CreateCall, and wait for CallConnected event of the call.

public class commandClass {
    // Class implementation...

    public void createCallCommand() {
        CallAutomationAsyncClient client = getCallAutomationAsyncClient(); // Should be the same instance as the one used in the example above.
        String callbackUrl = "<YOUR_CALL_BACK_URL>";
        CallInvite callInvite = new CallInvite(new CommunicationUserIdentifier("<TARGET_USER_ID>"));
        CreateCallResult result = client.createCall(callInvite, callbackUrl).block();

        try {
            // This will wait until CallConnected event is arrived or Timesout!
            CreateCallEventResult eventResult = result.waitForEventProcessorAsync(Duration.ofSeconds(30)).block();
            CallConnected returnedEvent = eventResult.successResult();
        } catch (Exception e) {
            // Timeout exception happend!
            // Call likely was never answered.
        }
    }
}

If timeout was not set when calling "waitForEventProcessorAsync", the default timeout is 4 minutes.

Troubleshooting

If you recieve a CommunicationErrorException with the messagae: "Action is invalid when call is not in Established state." This usually means the call has ended. This can occur if the participants all leave the call, or participants did not accept the call before the call timed out.

If you fail to start a call because of an HMAC validation error, be sure your access key is correct, and that you are passing in a valid conversation id.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Share via