Azure Communication CallingServer Service client library for Java - version 1.0.0-beta.4

  • Article

This package contains a Java SDK for Azure Communication CallingServer Service.

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

Getting started

Prerequisites

Include the package

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-callingserver</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>

Key concepts

At a high level the Azure Communication CallingServer API will support two kinds of scenarios:

  • In-call app: Contoso server app is a participant in the call.

  • Out-call app: Contoso server app is not a participant in the call - Server app can subscribe to events for calls between specific users or even all users belonging to the ACS azure resource.

Based on if the Contoso app join a call or not, APIs can be divided into two categories:

  • In-call APIs: Contoso app is one of the participant in a call. It can be applicable for app to person (A2P) or person to app (P2A) case, or multi-party/group calls that server apps joined as a participant to provide audio/prompt.

  • Out-of-call APIs: Contoso app can invoke these set of APIs without joining a call. It is applicable for actions on P2P calls, A2P calls, P2A calls and group calls.

Examples

Authenticate the client

You can provide the connection string using the connectionString() function of CallingServerClientBuilder. Once you initialized a CallingServerClient class, you can do the different server calling operations.

// Your connectionString retrieved from your Azure Communication Service
String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";

// Initialize the calling server client
final CallingServerClientBuilder builder = new CallingServerClientBuilder();
builder.connectionString(connectionString);
CallingServerClient callingServerClient = builder.buildClient();

Alternatively, calling clients can also be authenticated using a valid token credential. With this option, AZURE_CLIENT_SECRET, AZURE_CLIENT_ID and AZURE_TENANT_ID environment variables need to be set up for authentication.

// Your endpoint retrieved from your Azure Communication Service
String endpoint = "https://<resource-name>.communication.azure.com";

// Token credential used for managed identity authentication. Depends on `AZURE_CLIENT_SECRET`,
// `AZURE_CLIENT_ID`, and `AZURE_TENANT_ID` environment variables to be set up.
TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

// Initialize the calling server client
CallingServerClient callingServerClient  = new CallingServerClientBuilder()
    .endpoint(endpoint)
    .credential(tokenCredential)
    .buildClient();

Create call, Add participant and Hangup a call

Create a Call:

CommunicationIdentifier source = new CommunicationUserIdentifier("<acs-user-identity>");
CommunicationIdentifier firstCallee = new CommunicationUserIdentifier("<acs-user-identity-1>");
CommunicationIdentifier secondCallee = new CommunicationUserIdentifier("<acs-user-identity-2>");

List<CommunicationIdentifier> targets = Arrays.asList(firstCallee, secondCallee);

String callbackUri = "<callback-uri-for-notification>";

List<MediaType> requestedMediaTypes = Arrays.asList(MediaType.AUDIO, MediaType.VIDEO);

List<EventSubscriptionType> requestedCallEvents = Arrays.asList(
    EventSubscriptionType.DTMF_RECEIVED,
    EventSubscriptionType.PARTICIPANTS_UPDATED);

CreateCallOptions createCallOptions = new CreateCallOptions(
    callbackUri,
    requestedMediaTypes,
    requestedCallEvents);

CallConnection callConnection = callingServerClient.createCallConnection(source, targets, createCallOptions);

Add a participant to a Call:

CommunicationIdentifier thirdCallee = new CommunicationUserIdentifier("<acs-user-identity-3>");
callConnection.addParticipant(thirdCallee, "ACS User 3", "<string-for-tracing-responses>");

Hangup a Call:

callConnection.hangup();

Start, Pause, Resume, Stop and Get a recording

Start a Recording:

String serverCallId = "<serverCallId received from starting call>";
String recordingStateCallbackUri = "<webhook endpoint to which calling service can report status>";
ServerCall serverCall = callingServerClient.initializeServerCall(serverCallId);
StartCallRecordingResponse response = serverCall.startRecording(recordingStateCallbackUri);
String recordingId = response.getRecordingId();

Pause a Recording:

serverCall.pauseRecording(recordingId);

Resume a Recording:

serverCall.resumeRecording(recordingId);

Stop a Recording:

serverCall.stopRecording(recordingId);

Get the Recording State:

CallRecordingStateResult callRecordingStateResult = serverCall.getRecordingState(recordingId);

Download a Recording into a file:

callingServerClient.downloadTo(
            recordingUrl,
            Paths.get(filePath),
            null,
            true
        );

Play Audio in Call

Play Audio:

String audioFileUri = "<uri of the file to play>";
String audioFileId = "<a name to use for caching the audio file>";
String callbackUri = "<webhook endpoint to which calling service can report status>";
String context = "<Identifier for correlating responses>";
PlayAudioResponse playAudioResponse = serverCall.playAudio(audioFileUri, audioFileId, callbackUri, context);

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.

Next steps