Call Media - Play

Service:

Communication

API Version:

2023-10-15

Plays audio to participants in the call.

POST {endpoint}/calling/callConnections/{callConnectionId}:play?api-version=2023-10-15

URI Parameters

Name	In	Required	Type	Description
callConnectionId	path	True	string	The call connection id.
endpoint	path	True	string (url)	The endpoint of the Azure Communication resource.
api-version	query	True	string	Version of API to invoke.

Request Header

Name	Required	Type	Description
Authorization	True	string	An Azure Communication Services user access token.

Request Body

Name	Required	Type	Description
playSources	True	PlaySource[]	The source of the audio to be played.
operationCallbackUri		string	Set a callback URI that overrides the default callback URI set by CreateCall/AnswerCall for this operation. This setup is per-action. If this is not set, the default callback URI set by CreateCall/AnswerCall will be used.
operationContext		string	The value to identify context of the operation.
playOptions		PlayOptions	Defines options for playing the audio.
playTo		CommunicationIdentifierModel[]	The list of call participants play provided audio to. Plays to everyone in the call when not provided.

Responses

Name	Type	Description
202 Accepted		The service has accepted the play request and will begin processing it. You will receive either PlayCompleted or PlayFailed event at your specified callback URI to update you on the status of the request.
Other Status Codes	CommunicationErrorResponse	Error

Security

Authorization

An Azure Communication Services user access token.

Type: apiKey
In: header

Examples

CallMedia_Play

Sample request

HTTP

POST https://contoso.communications.azure.com/calling/callConnections/18dea47f-b081-4107-9a5c-4300819d2c6c:play?api-version=2023-10-15

{
  "playSources": [
    {
      "kind": "file",
      "playSourceCacheId": "string",
      "file": {
        "uri": "https://some.file.azure.com/sample.wav"
      }
    }
  ],
  "playTo": [
    {
      "kind": "communicationUser",
      "communicationUser": {
        "id": "8:acs:b9614373-fd0b-480c-8fd2-cb58b70eab9f_ae9e3307-f56e-44be-8934-80a63f080538"
      }
    }
  ],
  "playOptions": {
    "loop": true
  },
  "operationCallbackUri": "https://app.contoso.com/callback"
}

Sample response

Status code:

202

Definitions

Name	Description
FileSource
PlayOptions
PlayRequest
PlaySource
PlaySourceType	Defines the type of the play source
SsmlSource
TextSource
VoiceKind	Voice kind type

FileSource

Object

Name	Type	Description
uri	string	Uri for the audio file to be played

PlayOptions

Object

Name	Type	Description
loop	boolean	The option to play the provided audio source in loop when set to true

PlayRequest

Object

Name	Type	Description
operationCallbackUri	string	Set a callback URI that overrides the default callback URI set by CreateCall/AnswerCall for this operation. This setup is per-action. If this is not set, the default callback URI set by CreateCall/AnswerCall will be used.
operationContext	string	The value to identify context of the operation.
playOptions	PlayOptions	Defines options for playing the audio.
playSources	PlaySource[]	The source of the audio to be played.
playTo	CommunicationIdentifierModel[]	The list of call participants play provided audio to. Plays to everyone in the call when not provided.

PlaySource

Object

Name	Type	Description
file	FileSource	Defines the file source info to be used for play
kind	PlaySourceType	Defines the type of the play source
playSourceCacheId	string	Defines the identifier to be used for caching related media
ssml	SsmlSource	Defines the ssml(Speech Synthesis Markup Language) source info to be used for play
text	TextSource	Defines the text source info to be used for play

PlaySourceType

Enumeration

Defines the type of the play source

Value	Description
file
text
ssml

SsmlSource

Object

Name	Type	Description
customVoiceEndpointId	string	Endpoint where the custom voice was deployed.
ssmlText	string	Ssml string for the cognitive service to be played

TextSource

Object

Name	Type	Description
customVoiceEndpointId	string	Endpoint where the custom voice was deployed.
sourceLocale	string	Source language locale to be played Refer to available locales here: <seealso href="https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/language-support?tabs=stt-tts" />
text	string	Text for the cognitive service to be played
voiceKind	VoiceKind	Voice kind type
voiceName	string	Voice name to be played Refer to available Text-to-speech voices here: <seealso href="https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/language-support?tabs=stt-tts" />

VoiceKind

Enumeration

Voice kind type

Value	Description
male
female