Azure Communication Service Call Automation APIs (preview:2024-11-15)

2024/12/05 • 2 updated methods

Connect (updated)
Description :  Create a connection to a CallLocator.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Connect",
  "$parameters": {
    "connectRequest": {
      "$properties": {
        "callLocator": [
          {
            "#name": "kind",
            "Enum": {
              "new": [
                [
                  "groupCallLocator",
                  ""
                ],
                [
                  "serverCallLocator",
                  ""
                ],
                [
                  "roomCallLocator",
                  ""
                ]
              ],
              "old": [
                [
                  "unknown",
                  ""
                ],
                [
                  "groupCallLocator",
                  ""
                ],
                [
                  "serverCallLocator",
                  ""
                ],
                [
                  "roomCallLocator",
                  ""
                ]
              ]
            }
          }
        ]
      }
    }
  }
}

⚼ Request

POST:  /calling/callConnections:connect
{
connectRequest:
{
Description: The create connection request. ,
Required: True ,
}
{
callLocator:
{
Description: The call locator. ,
Required: True ,
}
{
groupCallId:
{
Description: The group call id ,
Required: False ,
}
string ,
serverCallId:
{
Description: The server call id. ,
Required: False ,
}
string ,
roomId:
{
Description: The Acs room id ,
Required: False ,
}
string ,
kind:
{
Description: The call locator kind. ,
Enum:
{
groupCallLocator: No description available. ,
serverCallLocator: No description available. ,
roomCallLocator: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
callbackUri:
{
Description: The callback URI. ,
Required: True ,
}
string ,
operationContext:
{
Description: Used by customers to correlate the request to the response event. ,
Required: False ,
}
string ,
callIntelligenceOptions:
{
Description: AI options for the call. ,
Required: False ,
}
{
cognitiveServicesEndpoint:
{
Description: The identifier of the Cognitive Service resource assigned to this call. ,
Required: False ,
}
string ,
}
,
mediaStreamingOptions:
{
Description: Media Streaming Configuration. ,
Required: False ,
}
{
transportUrl:
{
Description: Transport URL for media streaming ,
Required: True ,
}
string ,
transportType:
{
Description: The type of transport to be used for media streaming, eg. Websocket ,
Enum:
{
websocket: No description available. ,
}
,
Required: True ,
}
enum ,
contentType:
{
Description: Content type to stream, eg. audio ,
Enum:
{
audio: No description available. ,
}
,
Required: True ,
}
enum ,
audioChannelType:
{
Description: Audio channel type to stream, eg. unmixed audio, mixed audio ,
Enum:
{
mixed: No description available. ,
unmixed: No description available. ,
}
,
Required: True ,
}
enum ,
startMediaStreaming:
{
Description: Determines if the media streaming should be started immediately after call is answered or not. ,
Required: False ,
}
boolean ,
enableBidirectional:
{
Description: A value indicating whether bidirectional streaming is enabled. ,
Required: False ,
}
boolean ,
audioFormat:
{
Description: Specifies the audio format used for encoding, including sample rate and channel type. ,
Enum:
{
pcm16KMono: No description available. ,
pcm24KMono: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
transcriptionOptions:
{
Description: Live Transcription Configuration. ,
Required: False ,
}
{
transportUrl:
{
Description: Transport URL for live transcription ,
Required: True ,
}
string ,
transportType:
{
Description: The type of transport to be used for live transcription, eg. Websocket ,
Enum:
{
websocket: No description available. ,
}
,
Required: True ,
}
enum ,
locale:
{
Description: Defines the locale for the data e.g en-CA, en-AU ,
Required: True ,
}
string ,
speechRecognitionModelEndpointId:
{
Description: Endpoint where the custom model was deployed. ,
Required: False ,
}
string ,
startTranscription:
{
Description: Determines if the transcription should be started immediately after call is answered or not. ,
Required: True ,
}
boolean ,
enableIntermediateResults:
{
Description: Enables intermediate results for the transcribed speech. ,
Required: False ,
}
boolean ,
}
,
}
,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
Repeatability-Request-ID:
{
Description: 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. ,
Format: uuid ,
Required: False ,
}
string ,
Repeatability-First-Sent:
{
Description: 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. ,
Format: date-time-rfc1123 ,
Required: False ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
callConnectionId:
{
Description: The call connection id. ,
Required: False ,
}
string ,
serverCallId:
{
Description: The server call id. ,
Required: False ,
}
string ,
targets:
{
Description: The targets of the call. ,
Required: False ,
}
[
{
kind:
{
Description: The identifier kind. Only required in responses. ,
Enum:
{
unknown: No description available. ,
communicationUser: No description available. ,
phoneNumber: No description available. ,
microsoftTeamsUser: No description available. ,
microsoftTeamsApp: No description available. ,
}
,
Required: False ,
}
enum ,
rawId:
{
Description: Raw Id of the identifier. Optional in requests, required in responses. ,
Required: False ,
}
string ,
communicationUser:
{
Description: The communication user. ,
Required: False ,
}
{
id:
{
Description: The Id of the communication user. ,
Required: True ,
}
string ,
}
,
phoneNumber:
{
Description: The phone number. ,
Required: False ,
}
{
value:
{
Description: The phone number in E.164 format. ,
Required: True ,
}
string ,
}
,
microsoftTeamsUser:
{
Description: The Microsoft Teams user. ,
Required: False ,
}
{
userId:
{
Description: The Id of the Microsoft Teams user. If not anonymous, this is the AAD object Id of the user. ,
Required: True ,
}
string ,
isAnonymous:
{
Description: True if the Microsoft Teams user is anonymous. By default false if missing. ,
Required: False ,
}
boolean ,
cloud:
{
Description: The cloud that the Microsoft Teams user belongs to. By default 'public' if missing. ,
Enum:
{
public: No description available. ,
dod: No description available. ,
gcch: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
microsoftTeamsApp:
{
Description: The Microsoft Teams application. ,
Required: False ,
}
{
appId:
{
Description: The Id of the Microsoft Teams application. ,
Required: True ,
}
string ,
cloud:
{
Description: The cloud that the Microsoft Teams application belongs to. By default 'public' if missing. ,
Enum:
{
public: No description available. ,
dod: No description available. ,
gcch: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
}
,
]
,
callConnectionState:
{
Description: The state of the call connection. ,
Enum:
{
unknown: No description available. ,
connecting: No description available. ,
connected: No description available. ,
transferring: No description available. ,
transferAccepted: No description available. ,
disconnecting: No description available. ,
disconnected: No description available. ,
}
,
Required: False ,
}
enum ,
callbackUri:
{
Description: The callback URI. ,
Required: False ,
}
string ,
sourceCallerIdNumber:
{
Description: The source caller Id, a phone number, that's shown to the PSTN participant being invited. Required only when calling a PSTN callee. ,
Required: False ,
}
{
value:
{
Description: The phone number in E.164 format. ,
Required: True ,
}
string ,
}
,
sourceDisplayName:
{
Description: Display name of the call if dialing out to a pstn number. ,
Required: False ,
}
string ,
source:
{
Description: Source identity. ,
Required: False ,
}
{
kind:
{
Description: The identifier kind. Only required in responses. ,
Enum:
{
unknown: No description available. ,
communicationUser: No description available. ,
phoneNumber: No description available. ,
microsoftTeamsUser: No description available. ,
microsoftTeamsApp: No description available. ,
}
,
Required: False ,
}
enum ,
rawId:
{
Description: Raw Id of the identifier. Optional in requests, required in responses. ,
Required: False ,
}
string ,
communicationUser:
{
Description: The communication user. ,
Required: False ,
}
{
id:
{
Description: The Id of the communication user. ,
Required: True ,
}
string ,
}
,
phoneNumber:
{
Description: The phone number. ,
Required: False ,
}
{
value:
{
Description: The phone number in E.164 format. ,
Required: True ,
}
string ,
}
,
microsoftTeamsUser:
{
Description: The Microsoft Teams user. ,
Required: False ,
}
{
userId:
{
Description: The Id of the Microsoft Teams user. If not anonymous, this is the AAD object Id of the user. ,
Required: True ,
}
string ,
isAnonymous:
{
Description: True if the Microsoft Teams user is anonymous. By default false if missing. ,
Required: False ,
}
boolean ,
cloud:
{
Description: The cloud that the Microsoft Teams user belongs to. By default 'public' if missing. ,
Enum:
{
public: No description available. ,
dod: No description available. ,
gcch: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
microsoftTeamsApp:
{
Description: The Microsoft Teams application. ,
Required: False ,
}
{
appId:
{
Description: The Id of the Microsoft Teams application. ,
Required: True ,
}
string ,
cloud:
{
Description: The cloud that the Microsoft Teams application belongs to. By default 'public' if missing. ,
Enum:
{
public: No description available. ,
dod: No description available. ,
gcch: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
}
,
correlationId:
{
Description: The correlation ID. ,
Required: False ,
}
string ,
answeredBy:
{
Description: Identity of the answering entity. Only populated when identity is provided in the request. ,
Required: False ,
}
{
id:
{
Description: The Id of the communication user. ,
Required: True ,
}
string ,
}
,
mediaStreamingSubscription:
{
Description: The state of media streaming subscription for the call ,
Required: False ,
}
{
id:
{
Description: Subscription Id. ,
Required: False ,
}
string ,
state:
{
Description: Media streaming subscription state. ,
Enum:
{
disabled: No description available. ,
inactive: No description available. ,
active: No description available. ,
}
,
Required: False ,
}
enum ,
subscribedContentTypes:
{
Description: Subscribed media streaming content types. ,
Required: False ,
}
[
string ,
]
,
}
,
transcriptionSubscription:
{
Description: Transcription Subscription. ,
Required: False ,
}
{
id:
{
Description: Subscription Id. ,
Required: False ,
}
string ,
state:
{
Description: Transcription subscription state. ,
Enum:
{
disabled: No description available. ,
inactive: No description available. ,
active: No description available. ,
}
,
Required: False ,
}
enum ,
subscribedResultTypes:
{
Description: Subscribed transcription result types. ,
Required: False ,
}
[
string ,
]
,
}
,
answeredFor:
{
Description: Identity of the original Pstn target of an incoming Call. Only populated when the original target is a Pstn number. ,
Required: False ,
}
{
value:
{
Description: The phone number in E.164 format. ,
Required: True ,
}
string ,
}
,
}
CallRecording_StartRecording (updated)
Description :  Start recording the call.
Reference :  Link ¶

⚶ Changes

{
  "#id": "CallRecording_StartRecording",
  "$parameters": {
    "startCallRecording": {
      "$properties": {
        "callLocator": [
          {
            "#name": "kind",
            "Enum": {
              "new": [
                [
                  "groupCallLocator",
                  ""
                ],
                [
                  "serverCallLocator",
                  ""
                ],
                [
                  "roomCallLocator",
                  ""
                ]
              ],
              "old": [
                [
                  "unknown",
                  ""
                ],
                [
                  "groupCallLocator",
                  ""
                ],
                [
                  "serverCallLocator",
                  ""
                ],
                [
                  "roomCallLocator",
                  ""
                ]
              ]
            }
          }
        ]
      }
    }
  }
}

⚼ Request

POST:  /calling/recordings
{
startCallRecording:
{
Description: The request body of start call recording request. ,
Required: True ,
}
{
callLocator:
{
Description: The call locator. ,
Required: True ,
}
{
groupCallId:
{
Description: The group call id ,
Required: False ,
}
string ,
serverCallId:
{
Description: The server call id. ,
Required: False ,
}
string ,
roomId:
{
Description: The Acs room id ,
Required: False ,
}
string ,
kind:
{
Description: The call locator kind. ,
Enum:
{
groupCallLocator: No description available. ,
serverCallLocator: No description available. ,
roomCallLocator: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
recordingStateCallbackUri:
{
Description: The uri to send notifications to. ,
Required: False ,
}
string ,
recordingContentType:
{
Description: The content type of call recording. ,
Enum:
{
audio: No description available. ,
audioVideo: No description available. ,
}
,
Required: False ,
}
enum ,
recordingChannelType:
{
Description: The channel type of call recording. ,
Enum:
{
mixed: No description available. ,
unmixed: No description available. ,
}
,
Required: False ,
}
enum ,
recordingFormatType:
{
Description: The format type of call recording. ,
Enum:
{
wav: No description available. ,
mp3: No description available. ,
mp4: No description available. ,
}
,
Required: False ,
}
enum ,
audioChannelParticipantOrdering:
{
Description: The sequential order in which audio channels are assigned to participants in the unmixed recording. When 'recordingChannelType' is set to 'unmixed' and `audioChannelParticipantOrdering is not specified, the audio channel to participant mapping will be automatically assigned based on the order in which participant first audio was detected. Channel to participant mapping details can be found in the metadata of the recording. ,
Required: False ,
}
[
{
kind:
{
Description: The identifier kind. Only required in responses. ,
Enum:
{
unknown: No description available. ,
communicationUser: No description available. ,
phoneNumber: No description available. ,
microsoftTeamsUser: No description available. ,
microsoftTeamsApp: No description available. ,
}
,
Required: False ,
}
enum ,
rawId:
{
Description: Raw Id of the identifier. Optional in requests, required in responses. ,
Required: False ,
}
string ,
communicationUser:
{
Description: The communication user. ,
Required: False ,
}
{
id:
{
Description: The Id of the communication user. ,
Required: True ,
}
string ,
}
,
phoneNumber:
{
Description: The phone number. ,
Required: False ,
}
{
value:
{
Description: The phone number in E.164 format. ,
Required: True ,
}
string ,
}
,
microsoftTeamsUser:
{
Description: The Microsoft Teams user. ,
Required: False ,
}
{
userId:
{
Description: The Id of the Microsoft Teams user. If not anonymous, this is the AAD object Id of the user. ,
Required: True ,
}
string ,
isAnonymous:
{
Description: True if the Microsoft Teams user is anonymous. By default false if missing. ,
Required: False ,
}
boolean ,
cloud:
{
Description: The cloud that the Microsoft Teams user belongs to. By default 'public' if missing. ,
Enum:
{
public: No description available. ,
dod: No description available. ,
gcch: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
microsoftTeamsApp:
{
Description: The Microsoft Teams application. ,
Required: False ,
}
{
appId:
{
Description: The Id of the Microsoft Teams application. ,
Required: True ,
}
string ,
cloud:
{
Description: The cloud that the Microsoft Teams application belongs to. By default 'public' if missing. ,
Enum:
{
public: No description available. ,
dod: No description available. ,
gcch: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
}
,
]
,
channelAffinity:
{
Description: The channel affinity of call recording When 'recordingChannelType' is set to 'unmixed', if channelAffinity is not specified, 'channel' will be automatically assigned. Channel-Participant mapping details can be found in the metadata of the recording. /// ,
Required: False ,
}
[
{
channel:
{
Description: Channel number to which bitstream from a particular participant will be written. ,
Format: int32 ,
Required: False ,
}
integer ,
participant:
{
Description: The identifier for the participant whose bitstream will be written to the channel represented by the channel number. ,
Required: True ,
}
{
kind:
{
Description: The identifier kind. Only required in responses. ,
Enum:
{
unknown: No description available. ,
communicationUser: No description available. ,
phoneNumber: No description available. ,
microsoftTeamsUser: No description available. ,
microsoftTeamsApp: No description available. ,
}
,
Required: False ,
}
enum ,
rawId:
{
Description: Raw Id of the identifier. Optional in requests, required in responses. ,
Required: False ,
}
string ,
communicationUser:
{
Description: The communication user. ,
Required: False ,
}
{
id:
{
Description: The Id of the communication user. ,
Required: True ,
}
string ,
}
,
phoneNumber:
{
Description: The phone number. ,
Required: False ,
}
{
value:
{
Description: The phone number in E.164 format. ,
Required: True ,
}
string ,
}
,
microsoftTeamsUser:
{
Description: The Microsoft Teams user. ,
Required: False ,
}
{
userId:
{
Description: The Id of the Microsoft Teams user. If not anonymous, this is the AAD object Id of the user. ,
Required: True ,
}
string ,
isAnonymous:
{
Description: True if the Microsoft Teams user is anonymous. By default false if missing. ,
Required: False ,
}
boolean ,
cloud:
{
Description: The cloud that the Microsoft Teams user belongs to. By default 'public' if missing. ,
Enum:
{
public: No description available. ,
dod: No description available. ,
gcch: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
microsoftTeamsApp:
{
Description: The Microsoft Teams application. ,
Required: False ,
}
{
appId:
{
Description: The Id of the Microsoft Teams application. ,
Required: True ,
}
string ,
cloud:
{
Description: The cloud that the Microsoft Teams application belongs to. By default 'public' if missing. ,
Enum:
{
public: No description available. ,
dod: No description available. ,
gcch: No description available. ,
}
,
Required: False ,
}
enum ,
}
,
}
,
}
,
]
,
pauseOnStart:
{
Description: When set to true will start recording in Pause mode, which can be resumed. ,
Required: False ,
}
boolean ,
externalStorage:
{
Description: Optional property to specify location where recording will be stored ,
Required: False ,
}
{
recordingStorageKind:
{
Description: Defines the kind of external storage ,
Enum:
{
azureCommunicationServices: No description available. ,
azureBlobStorage: No description available. ,
}
,
Required: True ,
}
enum ,
recordingDestinationContainerUrl:
{
Description: Uri of a container or a location within a container ,
Format: uri ,
Required: False ,
}
string ,
}
,
}
,
api-version:
{
Description: Version of API to invoke. ,
Required: True ,
}
string ,
Repeatability-Request-ID:
{
Description: 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. ,
Format: uuid ,
Required: False ,
}
string ,
Repeatability-First-Sent:
{
Description: 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. ,
Format: date-time-rfc1123 ,
Required: False ,
}
string ,
}

⚐ Response (default)

{
error:
{
Description: The Communication Services error. ,
Required: True ,
}
{
code:
{
Description: The error code. ,
Required: True ,
}
string ,
message:
{
Description: The error message. ,
Required: True ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: Further details about specific errors that led to this error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Required: False ,
}
string ,
}
,
}

⚐ Response (200)

{
recordingId:
{
Required: False ,
}
string ,
recordingState:
{
Enum:
{
active: No description available. ,
inactive: No description available. ,
}
,
Required: False ,
}
enum ,
recordingKind:
{
Enum:
{
azureCommunicationServices: No description available. ,
teams: No description available. ,
teamsCompliance: No description available. ,
}
,
Required: False ,
}
enum ,
}