Skip navigation links

Azure SDK for Java Reference Documentation

Current version is 1.0.0-beta.4, click here for the index

Azure Communication CallingServer Service client library for Java

See: Description

Packages 
Package Description
com.azure.communication.callingserver
Package containing the classes for AzureCommunicationCallingServer.
com.azure.communication.callingserver.models
Package containing classes for AzureCommunicationCallingServerService.
com.azure.communication.callingserver.models.events
Package containing the event models for AzureCommunicationCallingServerService.
Current version is 1.0.0-beta.4, click here for the index

Azure Communication CallingServer Service client library for Java

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:

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

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

Skip navigation links

Visit the Azure for Java Developers site for more Java documentation, including quick starts, tutorials, and code samples.