Answer Call - Answer Call

Service:: Communication

API Version:: 2025-06-15

Answer a call using the IncomingCallContext from Event Grid.

POST {endpoint}/calling/callConnections:answer?api-version=2025-06-15

URI Parameters

Name	In	Required	Type	Description
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.
Repeatability-Request-ID		string (uuid)	If specified, the client directs that the request is repeatable; that is, that the client can make the request multiple times with the same Repeatability-Request-Id and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-Id is an opaque string representing a client-generated unique identifier for the request. It is a version 4 (random) UUID.
Repeatability-First-Sent		string (date-time-rfc1123)	If Repeatability-Request-ID header is specified, then Repeatability-First-Sent header must also be specified. The value should be the date and time at which the request was first created, expressed using the IMF-fixdate form of HTTP-date. Example: Sun, 06 Nov 1994 08:49:37 GMT.

Request Body

Name	Required	Type	Description
callbackUri	True	string	The callback uri.
incomingCallContext	True	string	The context associated with the call.
answeredBy		CommunicationUserIdentifierModel
callIntelligenceOptions		CallIntelligenceOptions	AI options for the call.
mediaStreamingOptions		MediaStreamingOptions: WebSocketMediaStreamingOptions	Media Streaming Options.
operationContext		string	A customer set value used to track the answering of a call.
transcriptionOptions		TranscriptionOptions: WebSocketTranscriptionOptions	Transcription Options.

Responses

Name	Type	Description
200 OK	CallConnectionProperties	Returns details of the call properties once the AnswerCall request is received by service. You will receive CallConnected event at your specified callback URI, once the call is connected.
Other Status Codes	CommunicationErrorResponse	Error

Security

Authorization

An Azure Communication Services user access token.

Type: apiKey
In: header

Examples

AnswerCall

Sample request

HTTP

POST https://contoso.communications.azure.com/calling/callConnections:answer?api-version=2025-06-15

{
  "incomingCallContext": "H4sIAAAAAAAEAMVVS2/bOBD+LzrspaElPiSSBoJFNnvYoNi0aHaBtpcFRQ5t1rIokLRTJ8h/X1J2soHRQ4A9lAdZ4ry+mflm/FhpNQy3PjnrtErOj9XysbLBb8uvM9WyEkul49J2ioEiGhlKADHVKiR7oVDXUGo5tkpa8k8zH9yglhuKuLQNkqLpEMZUNSZLNFfVRWVcnAZ1uFVbyP53EQLOtzCaybsx3ZSgnZFKKk4QgLGIybZFfU8oolIZzFrWGk6yzaDG1U6tYLaBMd9MKiSn3aROjjSRoAUHhG1PEDMdIGFlg4yRUmhChWQsm62dMdl+adUQ4aIKEP0u6KPft6RePV1Uyf/PmmmT5VijnlmMpD7VDLg4r9m4G4azgjWng37weD5nBTt6OS8YlcRyBhpJwD1iggFSbccQJVRJANW1gp4XLCc/uHETS/4qJaXX2dE6pSku61pNbgETMrBfxM1hgsUIqVzWe1Lrqda6iBBpmsXx9ZWW1vUe19aHDZja9pqBMRyBpQyxriVIgNBIGa11D9wy2tWE1Q7np6iPOH51lyXtLRinrsZ4D6FwQmdY28LEKfhV7nX8+XCfkZwAB/gGOv18WEccJ1A7M/0V1BgnHwq0/JmBYSoWEi84XTC+pIyLuszCXPBrPyYY0zPTsv57OBSOxJxoXjXzV3WzJs1D/+X22gy/36m762/vhk8PV5eXOWAm5gZKqDZ5/PCdc2L/vvmjbynGh3fhPus8lVIZFzLI7PBj8BNkOsPMRBc/nURXw+DvIbM7hR3MJnmWdNE6Itt7p2Gr3HAHKblxVcyfsp724x5CnPfizbh36WVDvpaUNIMfhplbb+1Xtp87hhfPr687lq/qB4HD9ec1vN98+OzhQ9Rfp26zKq34BS47ygVtBZdNS3AjMCnb0MU/d0NyH/NEH15WmYu/BZ+7q2L6b1oN9LvVS3se5z+B4w6lWIOSHOl5+rmiSJoOI9b0jZZATMPUD7bsm5ZGjrsKfjfNcb+faPH0LyoNW7KCBgAA",
  "callbackUri": "https://app.contoso.com/callback",
  "operationContext": "operationContext",
  "callIntelligenceOptions": {
    "cognitiveServicesEndpoint": "string"
  },
  "answeredBy": {
    "id": "+11234567890"
  },
  "mediaStreamingOptions": {
    "audioChannelType": "mixed",
    "transportUrl": "string",
    "transportType": "websocket",
    "contentType": "audio",
    "startMediaStreaming": true,
    "enableBidirectional": true,
    "audioFormat": "pcm16KMono"
  },
  "transcriptionOptions": {
    "locale": "en-US",
    "transportUrl": "string",
    "transportType": "websocket",
    "speechModelEndpointId": "string",
    "startTranscription": true,
    "enableIntermediateResults": true
  }
}

Sample response

Status code:: 200

{
  "callConnectionId": "18dea47f-b081-4107-9a5c-4300819d2c6c",
  "serverCallId": "aHR0cHM6Ly9jb252ZXJzYXRpb251cmwvdGVzdA",
  "sourceCallerIdNumber": {
    "value": "+18440123456"
  },
  "source": {
    "kind": "communicationUser",
    "communicationUser": {
      "id": "8:acs:b9614373-fd0b-480c-8fd2-cb58b70eab9f_da7be3a9-8788-42a6-85c6-56b2cf784fce"
    }
  },
  "targets": [
    {
      "kind": "communicationUser",
      "communicationUser": {
        "id": "8:acs:b9614373-fd0b-480c-8fd2-cb58b70eab9f_0f50d091-5bd3-448b-884d-44be7037d9b9"
      }
    }
  ],
  "callConnectionState": "connected",
  "callbackUri": "https://app.contoso.com/callback",
  "mediaStreamingSubscription": {
    "id": "23dea47f-b081-4107-9a5c-4300819d2caa",
    "state": "active",
    "subscribedContentTypes": [
      "audio"
    ]
  },
  "transcriptionSubscription": {
    "id": "45dea47f-b081-4107-9a5c-4300819d2caa",
    "state": "active",
    "subscribedResultTypes": [
      "final"
    ]
  },
  "answeredFor": {
    "value": "+11234567890"
  }
}

Definitions

Name	Description
AnswerCallRequest	The request payload for answering the call.
AudioFormat	The audio format used for encoding, including sample rate and channel type. The default is Pcm16KMono.
CallConnectionProperties	Properties of a call connection
CallConnectionStateModel	The state of the call connection.
CallIntelligenceOptions	AI options for the call.
MediaStreamingAudioChannelType	The audio channel type to stream, e.g., unmixed audio, mixed audio.
MediaStreamingContentType
MediaStreamingSubscription	Media streaming Subscription Object.
MediaStreamingSubscriptionState	Media streaming subscription state.
StreamingTransportType	Defines the transport type used for streaming. Note that future values may be introduced that are not currently documented.
TranscriptionResultType
TranscriptionSubscription	Transcription Subscription Object.
TranscriptionSubscriptionState	Transcription subscription state.
WebSocketMediaStreamingOptions	Represents the options for WebSocket transport.
WebSocketTranscriptionOptions	Represents the options for WebSocket transport.

AnswerCallRequest

Object

The request payload for answering the call.

Name	Type	Description
answeredBy	CommunicationUserIdentifierModel
callIntelligenceOptions	CallIntelligenceOptions	AI options for the call.
callbackUri	string	The callback uri.
incomingCallContext	string	The context associated with the call.
mediaStreamingOptions	MediaStreamingOptions: WebSocketMediaStreamingOptions	Media Streaming Options.
operationContext	string	A customer set value used to track the answering of a call.
transcriptionOptions	TranscriptionOptions: WebSocketTranscriptionOptions	Transcription Options.

AudioFormat

Enumeration

The audio format used for encoding, including sample rate and channel type. The default is Pcm16KMono.

Value	Description
pcm16KMono
pcm24KMono

CallConnectionProperties

Object

Properties of a call connection

Name	Type	Description
answeredBy	CommunicationUserIdentifierModel
answeredFor	PhoneNumberIdentifierModel
callConnectionId	string	The call connection id.
callConnectionState	CallConnectionStateModel	The state of the call connection.
callbackUri	string	The callback URI.
correlationId	string	The correlation ID.
mediaStreamingSubscription	MediaStreamingSubscription	The state of media streaming subscription for the call
serverCallId	string	The server call id.
source	CommunicationIdentifierModel
sourceCallerIdNumber	PhoneNumberIdentifierModel
sourceDisplayName	string	Display name of the call if dialing out to a pstn number.
targets	CommunicationIdentifierModel[]	The targets of the call.
transcriptionSubscription	TranscriptionSubscription	Transcription Subscription.

CallConnectionStateModel

Enumeration

The state of the call connection.

Value	Description
unknown
connecting
connected
transferring
transferAccepted
disconnecting
disconnected

CallIntelligenceOptions

Object

AI options for the call.

Name	Type	Description
cognitiveServicesEndpoint	string	The identifier of the Cognitive Service resource assigned to this call.

MediaStreamingAudioChannelType

Enumeration

The audio channel type to stream, e.g., unmixed audio, mixed audio.

Value	Description
mixed
unmixed

MediaStreamingContentType

Enumeration

Value	Description
audio

MediaStreamingSubscription

Object

Media streaming Subscription Object.

Name	Type	Description
id	string	Subscription Id.
state	MediaStreamingSubscriptionState	Media streaming subscription state.
subscribedContentTypes	MediaStreamingContentType[]	Subscribed media streaming content types.

MediaStreamingSubscriptionState

Enumeration

Media streaming subscription state.

Value	Description
disabled
inactive
active

StreamingTransportType

Enumeration

Defines the transport type used for streaming. Note that future values may be introduced that are not currently documented.

Value	Description
websocket

TranscriptionResultType

Enumeration

Value	Description
final
intermediate

TranscriptionSubscription

Object

Transcription Subscription Object.

Name	Type	Description
id	string	Subscription Id.
locale	string	Specifies the locale used for transcription, e.g., en-CA or en-AU.
state	TranscriptionSubscriptionState	Transcription subscription state.
subscribedResultTypes	TranscriptionResultType[]	Subscribed transcription result types.

TranscriptionSubscriptionState

Enumeration

Transcription subscription state.

Value	Description
disabled
inactive
active

WebSocketMediaStreamingOptions

Object

Represents the options for WebSocket transport.

Name	Type	Description
audioChannelType	MediaStreamingAudioChannelType	The audio channel type to stream, e.g., unmixed audio, mixed audio.
audioFormat	AudioFormat	The audio format used for encoding, including sample rate and channel type. The default is Pcm16KMono.
contentType	MediaStreamingContentType
enableBidirectional	boolean	A value indicating whether bidirectional streaming is enabled.
enableDtmfTones	boolean	A value that indicates whether to stream the DTMF tones.
startMediaStreaming	boolean	A value indicating whether the media streaming should start immediately after the call is answered.
transportType	string: websocket	Defines the transport type used for streaming. Note that future values may be introduced that are not currently documented.
transportUrl	string	The transport URL for media streaming.

WebSocketTranscriptionOptions

Object

Represents the options for WebSocket transport.

Name	Type	Description
enableIntermediateResults	boolean	Enables intermediate results for the transcribed speech.
locale	string	Specifies the Locale used for transcription, e.g., en-CA or en-AU.
speechModelEndpointId	string	The ID of the deployed custom model in GUID format. The GUID is generated by Azure Speech Studio, e.g., a259c255-1cdw-4ed7-a693-dd58563b6f6a.
startTranscription	boolean	Indicates whether the transcription should start immediately after the call is answered.
transportType	string: websocket	Defines the transport type used for streaming. Note that future values may be introduced that are not currently documented.
transportUrl	string	The URL used for live transcription transport.

Share via

Answer Call - Answer Call

URI Parameters

Request Header

Request Body

Responses

Security

Authorization

Examples

AnswerCall

Sample request

Sample response

Definitions

AnswerCallRequest

AudioFormat

CallConnectionProperties

CallConnectionStateModel

CallIntelligenceOptions

MediaStreamingAudioChannelType

MediaStreamingContentType

MediaStreamingSubscription

MediaStreamingSubscriptionState

StreamingTransportType

TranscriptionResultType

TranscriptionSubscription

TranscriptionSubscriptionState

WebSocketMediaStreamingOptions

WebSocketTranscriptionOptions