Customize voice prompts to users with Play action
Important
This feature of Azure Communication Services is currently in preview.
Preview APIs and SDKs are provided without a service-level agreement. We recommend that you don't use them for production workloads. Some features might not be supported, or they might have constrained capabilities.
For more information, review Supplemental Terms of Use for Microsoft Azure Previews.
This guide will help you get started with playing audio files to participants by using the play action provided through Azure Communication Services Call Automation SDK.
Prerequisites
- Azure account with an active subscription, for details see Create an account for free.
- Azure Communication Services resource. See Create an Azure Communication Services resource. Save the connection string for this resource.
- Create a new web service application using the Call Automation SDK.
- The latest .NET library for your operating system.
- Obtain the NuGet package from the Azure SDK Dev Feed
Create a new C# application
In the console window of your operating system, use the dotnet
command to create a new web application.
dotnet new web -n MyApplication
Install the NuGet package
During the preview phase, the NuGet package can be obtained by configuring your package manager to use the Azure SDK Dev Feed from here
Prepare your audio file
Create an audio file, if you don't already have one, to use for playing prompts and messages to participants. The audio file must be hosted in a location that is accessible to ACS with support for authentication. Keep a copy of the URL available for you to use when requesting to play the audio file. The audio file that ACS supports needs to be WAV, mono and 16 KHz sample rate.
You can test creating your own audio file using our Speech synthesis with Audio Content Creation tool.
Establish a call
By this point you should be familiar with starting calls, if you need to learn more about making a call, follow our quickstart. In this quickstart, we'll answer an incoming call.
Play audio
Once the call has been established, there are multiple options for how you may wish to play the audio. You can play audio to the participant that has just joined the call or play audio to all the participants in the call.
Play audio - Specific participant
In this scenario audio will be played to a specific participant that is specified in the request.
var targetUser = new PhoneNumberIdentifier(<target>);
var callMedia = callAutomationClient.GetCallConnection(<callConnectionId>).GetCallMedia();
var fileSource = new FileSource(new Uri(<audioUri>));
var playResponse = await callMedia.PlayAsync(fileSource, new PhoneNumberIdentifier[] { targetUser });
Assert.AreEqual(202, playResponse.Status) // The request was accepted.
Play audio - All participants
In this scenario audio will be played to all participants on the call.
var callMedia = callAutomationClient.GetCallConnection(<callConnectionId>).GetCallMedia();
var fileSource = new FileSource(new Uri(<audioUri>));
var playResponse = await callMedia.PlayToAllAsync(fileSource);
Assert.AreEqual(202, playResponse.Status) // The request was accepted.
Play audio on loop
You can use the loop option to play hold music that loops until your application is ready to accept the caller. Or progress the caller to the next logical step based on your applications business logic.
var callMedia = callAutomationClient.GetCallConnection(<callConnectionId>).GetCallMedia();
var fileSource = new FileSource(new Uri(<audioUri>));
var playOptions = new PlayOptions()
{
Loop = true
};
var playResponse = await callMedia.PlayToAllAsync(fileSource, playOptions);
Assert.AreEqual(202, playResponse.Status) // The request was accepted.
Enhance play with audio file caching
If you'll be playing the same audio file multiple times, your application can provide us the sourceID for the audio file. ACS will cache this audio file for 1 hour.
var targetUser = new PhoneNumberIdentifier(<target>);
var callMedia = callAutomationClient.GetCallConnection(<callConnectionId>).GetCallMedia();
var fileSource = new FileSource(new Uri(<audioUri>)) {
PlaySourceId = "<playSourceId>"
};
var playResponse = await callMedia.PlayAsync(fileSource, new PhoneNumberIdentifier[] { targetUser });
Assert.AreEqual(202, playResponse.Status) // The request was accepted.
Handle play action event updates
Your application will receive action lifecycle event updates on the callback URL that was provided to Call Automation service at the time of answering the call. Below is an example of a successful play event update.
[{
"id": "704a7a96-4d74-4ebe-9cd0-b7cc39c3d7b1",
"source": "calling/callConnections/<callConnectionId>/PlayCompleted",
"type": "Microsoft.Communication.PlayCompleted",
"data": {
"resultInfo": {
"code": 200,
"subCode": 0,
"message": "Action completed successfully."
},
"type": "playCompleted",
"callConnectionId": "<callConnectionId>",
"serverCallId": "<serverCallId>",
"correlationId": "<correlationId>"
},
"time": "2022-08-12T03:13:25.0252763+00:00",
"specversion": "1.0",
"datacontenttype": "application/json",
"subject": "calling/callConnections/<callConnectionId>/PlayCompleted"
}]
To learn more about other supported events, visit the Call Automation overview document.
Cancel play action
Cancel all media operations, all pending media operations will be canceled. This action will also cancel other queued play actions.
var callMedia = callAutomationClient.GetCallConnection(<callConnectionId>).GetCallMedia();
var cancelResponse = await callMedia.CancelAllMediaOperations();
Assert.AreEqual(202, cancelResponse.Status) // The request was accepted.
Prerequisites
- Azure account with an active subscription, for details see Create an account for free.
- Azure Communication Services resource. See Create an Azure Communication Services resource
- Create a new web service application using the Call Automation SDK.
- Java Development Kit version 8 or above.
- Apache Maven.
Create a new Java application
In your terminal or command window, navigate to the directory where you would like to create your Java application. Run the command below to generate the Java project from the maven-archetype-quickstart template.
mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
The command above creates a directory with the same name as artifactId
argument. Under this directory, src/main/java
directory contains the project source code, src/test/java
directory contains the test source.
You'll notice that the 'generate' step created a directory with the same name as the artifactId. Under this directory, src/main/java
directory contains source code, src/test/java
directory contains tests, and pom.xml
file is the project's Project Object Model, or POM.
Update your applications POM file to use Java 8 or higher.
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
Configure Azure SDK Dev Feed
Since the Call Automation SDK version used in this quickstart isn't yet available in Maven Central Repository, we need to add an Azure Artifacts development feed, which contains the latest version of Call Automation SDK.
Add the azure-sdk-for-java feed to your pom.xml
. Follow the instructions after clicking the "Connect to Feed" button.
Add package references
In your POM file, add the following reference for the project.
azure-communication-callingserver
Azure Communication Services Call Automation SDK package is retrieved from the Azure SDK Dev Feed configured above.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-callingserver</artifactId>
<version>1.0.0-alpha.20220829.1</version>
</dependency>
Prepare your audio file
Create an audio file, if you don't already have one, to use for playing prompts and messages to participants. The audio file must be hosted in a location that is accessible to ACS with support for authentication. Keep a copy of the URL available for you to use when requesting to play the audio file. The audio file ACS supports needs to be WAV, mono and 16 KHz sample rate.
You can test creating your own audio file using our Speech synthesis with Audio Content Creation tool.
Update App.java with code
In your editor of choice, open App.java file and update it with the code provided in Update app.java with code section.
Establish a call
By this point you should be familiar with starting calls, if you need to learn more about making a call, follow our quickstart. In this quickstart, we'll answer an incoming call.
Play audio
Once the call has been established, there are multiple options for how you may wish to play the audio. You can play audio to the participant that has just joined the call or play audio to all the participants in the call.
Play audio - Specific participant
In this scenario audio will be played to a specific participant that is specified in the request.
var targetUser = new PhoneNumberIdentifier(<target>);
var callConnection = callAutomationAsyncClient.getCallConnectionAsync(<callConnectionId>);
var fileSource = new FileSource().setUri(<audioUrl>);
var playResponse = callConnection.getCallMediaAsync().playWithResponse(
fileSource,
Collections.singletonList(targetUser),
new PlayOptions()
).block();
assertEquals(202, playResponse.getStatusCode()); // The request was accepted
Play audio - All participants
In this scenario audio will be played to all participants on the call.
var callConnection = callAutomationAsyncClient.getCallConnectionAsync(<callConnectionId>);
var fileSource = new FileSource().setUri(<audioUrl>);
var playResponse = callConnection.getCallMediaAsync().playToAllWithResponse(
fileSource,
new PlayOptions()
).block();
assertEquals(202, playResponse.getStatusCode()); // The request was accepted
Play audio on loop
You can use the loop option to play hold music that loops until your application is ready to accept the caller or progress the caller to the next logical step based on your applications business logic.
var callConnection = callAutomationAsyncClient.getCallConnectionAsync(<callConnectionId>);
var fileSource = new FileSource().setUri(<audioUrl>);
var playOptions = new PlayOptions().setLoop(true);
var playResponse = callConnection.getCallMediaAsync().playToAllWithResponse(
fileSource,
playOptions
).block();
assertEquals(202, playResponse.getStatusCode()); // The request was accepted
Enhance play with audio file caching
If you'll be playing the same audio file multiple times, your application can provide us the sourceID for the audio file. ACS will cache this audio file for 1 hour.
var targetUser = new PhoneNumberIdentifier(<target>);
var callConnection= callAutomationAsyncClient.getCallConnectionAsync(<callConnectionId>);
var fileSource = new FileSource().setUri(<audioUrl>).setPlaySourceId(<sourceId>);
var playResponse = callConnection.getCallMediaAsync().playWithResponse(
fileSource,
Collections.singletonList(targetUser),
new PlayOptions()
).block();
assertEquals(202, playResponse.getStatusCode()); // The request was accepted
Handle play action event updates
Your application will receive action lifecycle event updates on the callback URL that was provided to Call Automation service at the time of answering the call. Below is an example of a successful play event update.
[{
"id": "704a7a96-4d74-4ebe-9cd0-b7cc39c3d7b1",
"source": "calling/callConnections/<callConnectionId>/PlayCompleted",
"type": "Microsoft.Communication.PlayCompleted",
"data": {
"resultInfo": {
"code": 200,
"subCode": 0,
"message": "Action completed successfully."
},
"type": "playCompleted",
"callConnectionId": "<callConnectionId>",
"serverCallId": "<serverCallId>",
"correlationId": "<correlationId>"
},
"time": "2022-08-12T03:13:25.0252763+00:00",
"specversion": "1.0",
"datacontenttype": "application/json",
"subject": "calling/callConnections/<callConnectionId>/PlayCompleted"
}]
To learn more about other supported events, visit the Call Automation overview document.
Cancel play action
Cancel all media operations, all pending media operations will be canceled. This action will also cancel other queued play actions.
var callConnection = callAutomationAsyncClient.getCallConnectionAsync(<callConnectionId>);
var cancelResponse = callConnection.getCallMediaAsync().cancelAllMediaOperationsWithResponse().block();
assertEquals(202, cancelResponse.getStatusCode()); // The request was accepted
Clean up resources
If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about cleaning up resources.
Next steps
- Learn more about Call Automation
- Learn more about Gathering user input in a call
Feedback
Submit and view feedback for