Call Media - Hold

Service:: Communication

API Version:: 2026-03-12

Hold participant from the call using identifier.

POST {endpoint}/calling/callConnections/{callConnectionId}:hold?api-version=2026-03-12

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 Service resource.
api-version	query	True	string	Version of the 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
targetParticipant	True	CommunicationIdentifierModel
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	Used by customers when calling mid-call actions to correlate the request to the response event.
playSourceInfo		PlaySource

Responses

Name	Type	Description
200 OK		Returns the hold participant response
Other Status Codes	CommunicationErrorResponse	Error

Security

Authorization

An Azure Communication Services user access token.

Type: apiKey
In: header

Examples

CallMedia_Hold

Sample request

HTTP

POST https://contoso.communications.azure.com/calling/callConnections/18dea47f-b081-4107-9a5c-4300819d2c6c:hold?api-version=2026-03-12

{
  "targetParticipant": {
    "kind": "communicationUser",
    "communicationUser": {
      "id": "8:acs:b9614373-fd0b-480c-8fd2-cb58b70eab9f_0f50d091-5bd3-448b-884d-44be7037d9b9"
    }
  },
  "playSourceInfo": {
    "kind": "file",
    "file": {
      "uri": "https://some.file.azure.com/sample.wav"
    }
  }
}

Sample response

Status code:: 200

Definitions

Name	Description
FileSource
HoldRequest	The request payload for holding participant from the call.
PlaySource
PlaySourceType	Defines the types of play source
SsmlSource
TextSource
VoiceKind	Audio kind type

FileSource

Object

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

HoldRequest

Object

The request payload for holding participant from the call.

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	Used by customers when calling mid-call actions to correlate the request to the response event.
playSourceInfo	PlaySource
targetParticipant	CommunicationIdentifierModel

PlaySource

Object

Name	Type	Description
file	FileSource
kind	PlaySourceType	Defines the types of play source
playSourceCacheId	string	Defines the identifier to be used for caching related media
ssml	SsmlSource
text	TextSource

PlaySourceType

Enumeration

Defines the types of 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	Audio 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

Audio kind type

Value	Description
male
female