Create Call - Create Call

Service:

Communication

API Version:

2023-10-15

Create an outbound call.

POST {endpoint}/calling/callConnections?api-version=2023-10-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.
targets	True	CommunicationIdentifierModel[]	The targets of the call.
callIntelligenceOptions		CallIntelligenceOptions	AI options for the call.
operationContext		string	A customer set value used to track the answering of a call.
source		CommunicationUserIdentifierModel
sourceCallerIdNumber		PhoneNumberIdentifierModel
sourceDisplayName		string	Display name of the call if dialing out to a pstn number

Responses

Name	Type	Description
201 Created	CallConnectionProperties	Returns details of the call properties once the CreateCall 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

CreateCall

Sample request

HTTP

POST https://contoso.communications.azure.com/calling/callConnections?api-version=2023-10-15

{
  "targets": [
    {
      "kind": "communicationUser",
      "communicationUser": {
        "id": "8:acs:b9614373-fd0b-480c-8fd2-cb58b70eab9f_0f50d091-5bd3-448b-884d-44be7037d9b9"
      }
    }
  ],
  "callbackUri": "https://app.contoso.com/callback"
}

Sample response

Status code:

201

{
  "callConnectionId": "18dea47f-b081-4107-9a5c-4300819d2c6c",
  "serverCallId": "aHR0cHM6Ly9jb252ZXJzYXRpb251cmwvdGVzdA",
  "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"
}

Definitions

Name	Description
CallConnectionProperties	Properties of a call connection
CallConnectionStateModel	The state of the call connection.
CallIntelligenceOptions	AI options for the call.
CreateCallRequest	The request payload for creating the call.

CallConnectionProperties

Object

Properties of a call connection

Name	Type	Description
answeredBy	CommunicationUserIdentifierModel
callConnectionId	string	The call connection id.
callConnectionState	CallConnectionStateModel	The state of the call connection.
callbackUri	string	The callback URI.
correlationId	string	The correlation ID.
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.

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.

CreateCallRequest

Object

The request payload for creating the call.

Name	Type	Description
callIntelligenceOptions	CallIntelligenceOptions	AI options for the call.
callbackUri	string	The callback URI.
operationContext	string	A customer set value used to track the answering of a call.
source	CommunicationUserIdentifierModel
sourceCallerIdNumber	PhoneNumberIdentifierModel
sourceDisplayName	string	Display name of the call if dialing out to a pstn number
targets	CommunicationIdentifierModel[]	The targets of the call.