CallAutomationClient Class

A client to interact with the AzureCommunicationService CallAutomation service. Call Automation provides developers the ability to build server-based, intelligent call workflows, and call recording for voice and PSTN channels.

Constructor

CallAutomationClient(endpoint: str, credential: TokenCredential | AzureKeyCredential, *, api_version: str | None = None, source: CommunicationUserIdentifier | None = None, **kwargs)

Parameters

Name	Description
endpoint Required	str The endpoint of the Azure Communication resource.
credential Required	TokenCredential or AzureKeyCredential The access key we use to authenticate against the service.

Keyword-Only Parameters

Name	Description
api_version	str Azure Communication Call Automation API version. Default value: None
source	CommunicationUserIdentifier ACS User Identity to be used when the call is created or answered. If not provided, service will generate one. Default value: None

Methods

answer_call	Answer incoming call with Azure Communication Service's IncomingCall event Retrieving IncomingCall event can be set on Azure Communication Service's Azure Portal.
close
connect_call
create_call	Create a call connection request to a target identity.
create_group_call	Create a call connection request to a list of multiple target identities. This will call all targets simultaneously, and whoever answers the call will join the call.
delete_recording	Delete a call recording from given recording url.
download_recording	Download a stream of the call recording.
from_connection_string	Create CallAutomation client from a Connection String.
get_call_connection	Get CallConnectionClient object. Interact with ongoing call with CallConnectionClient.
get_recording_properties	Get call recording properties and its state.
pause_recording	Pause recording the call.
redirect_call	Redirect incoming call to a specific target.
reject_call	Reject incoming call.
resume_recording	Resume recording the call.
start_recording
stop_recording	Stop recording the call.

answer_call

Answer incoming call with Azure Communication Service's IncomingCall event Retrieving IncomingCall event can be set on Azure Communication Service's Azure Portal.

answer_call(incoming_call_context: str, callback_url: str, *, cognitive_services_endpoint: str | None = None, operation_context: str | None = None, media_streaming: MediaStreamingOptions | None = None, transcription: TranscriptionOptions | None = None, **kwargs) -> CallConnectionProperties

Parameters

Name	Description
incoming_call_context Required	str This can be read from body of IncomingCall event. Use this value to answer incoming call.
callback_url Required	str The call back url for receiving events.

Keyword-Only Parameters

Name	Description
cognitive_services_endpoint	str The endpoint url of the Azure Cognitive Services resource attached. Default value: None
operation_context	str The operation context. Default value: None
media_streaming	MediaStreamingOptions or None Media Streaming Options. Default value: None
transcription	TranscriptionOptions or None Configuration of live transcription. Default value: None

Returns

Type	Description
CallConnectionProperties	CallConnectionProperties

Exceptions

Type	Description
HttpResponseError

close

close() -> None

connect_call

connect_call(callback_url: str, *, server_call_id: str, cognitive_services_endpoint: str | None = None, operation_context: str | None = None, media_streaming: 'MediaStreamingOptions' | None = None, transcription: 'TranscriptionOptions' | None = None, **kwargs) -> CallConnectionProperties

Parameters

Name	Description
callback_url Required

create_call

Create a call connection request to a target identity.

create_call(target_participant: CommunicationIdentifier | List[CommunicationIdentifier], callback_url: str, *, source_caller_id_number: PhoneNumberIdentifier | None = None, source_display_name: str | None = None, operation_context: str | None = None, cognitive_services_endpoint: str | None = None, media_streaming: MediaStreamingOptions | None = None, transcription: TranscriptionOptions | None = None, **kwargs) -> CallConnectionProperties

Parameters

Name	Description
target_participant Required	CommunicationIdentifier or list[CommunicationIdentifier] Call invitee's information.
callback_url Required	str The call back url where callback events are sent.

Keyword-Only Parameters

Name	Description
operation_context	str or None Value that can be used to track the call and its associated events. Default value: None
source_caller_id_number	PhoneNumberIdentifier or None The source caller Id, a phone number, that's shown to the PSTN participant being invited. Required only when calling a PSTN callee. Default value: None
source_display_name	str or None Display name of the caller. Default value: None
cognitive_services_endpoint	str or None The identifier of the Cognitive Service resource assigned to this call. Default value: None
media_streaming	MediaStreamingOptions or None Media Streaming Options. Default value: None
transcription	TranscriptionOptions or None Configuration of live transcription. Default value: None

Returns

Type	Description
CallConnectionProperties	CallConnectionProperties

Exceptions

Type	Description
HttpResponseError

create_group_call

Create a call connection request to a list of multiple target identities. This will call all targets simultaneously, and whoever answers the call will join the call.

create_group_call(target_participants: List[CommunicationIdentifier], callback_url: str, *, source_caller_id_number: PhoneNumberIdentifier | None = None, source_display_name: str | None = None, operation_context: str | None = None, cognitive_services_endpoint: str | None = None, **kwargs) -> CallConnectionProperties

Parameters

Name	Description
target_participants Required	list[CommunicationIdentifier] A list of targets.
callback_url Required	str The call back url for receiving events.

Keyword-Only Parameters

Name	Description
source_caller_id_number	PhoneNumberIdentifier The source caller Id, a phone number, that's shown to the PSTN participant being invited. Required only when calling a PSTN callee. Default value: None
source_display_name	str Display name of the caller. Default value: None
operation_context	str Value that can be used to track the call and its associated events. Default value: None
cognitive_services_endpoint	str The identifier of the Cognitive Service resource assigned to this call. Default value: None

Returns

Type	Description
CallConnectionProperties	CallConnectionProperties

Exceptions

Type	Description
HttpResponseError

delete_recording

Delete a call recording from given recording url.

delete_recording(recording_url: str, **kwargs) -> None

Parameters

Name	Description
recording_url Required	str Recording's url.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError

download_recording

Download a stream of the call recording.

download_recording(recording_url: str, *, offset: int = None, length: int = None, **kwargs) -> Iterable[bytes]

Parameters

Name	Description
recording_url Required	str Recording's url to be downloaded

Keyword-Only Parameters

Name	Description
offset	int If provided, only download the bytes of the content in the specified range. Offset of starting byte. Default value: None
length	int If provided, only download the bytes of the content in the specified range. Length of the bytes to be downloaded. Default value: None

Returns

Type	Description
Iterable[bytes]	Iterable[bytes]

Exceptions

Type	Description
HttpResponseError

from_connection_string

Create CallAutomation client from a Connection String.

from_connection_string(conn_str: str, **kwargs) -> CallAutomationClient

Parameters

Name	Description
conn_str Required	str A connection string to an Azure Communication Service resource.

Returns

Type	Description
CallAutomationClient	CallAutomationClient

get_call_connection

Get CallConnectionClient object. Interact with ongoing call with CallConnectionClient.

get_call_connection(call_connection_id: str, **kwargs) -> CallConnectionClient

Parameters

Name	Description
call_connection_id Required	str CallConnectionId of ongoing call.

Returns

Type	Description
CallConnectionClient	CallConnectionClient

get_recording_properties

Get call recording properties and its state.

get_recording_properties(recording_id: str, **kwargs) -> RecordingProperties

Parameters

Name	Description
recording_id Required	str The recording id.

Returns

Type	Description
RecordingProperties	RecordingProperties

Exceptions

Type	Description
HttpResponseError

pause_recording

Pause recording the call.

pause_recording(recording_id: str, **kwargs) -> None

Parameters

Name	Description
recording_id Required	str The recording id.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError

redirect_call

Redirect incoming call to a specific target.

redirect_call(incoming_call_context: str, target_participant: CommunicationIdentifier, **kwargs) -> None

Parameters

Name	Description
incoming_call_context Required	str This can be read from body of IncomingCall event. Use this value to redirect incoming call.
target_participant Required	CommunicationIdentifier The target identity to redirect the call to.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError

reject_call

Reject incoming call.

reject_call(incoming_call_context: str, *, call_reject_reason: str | CallRejectReason | None = None, **kwargs) -> None

Parameters

Name	Description
incoming_call_context Required	str This can be read from body of IncomingCall event. Use this value to reject incoming call.

Keyword-Only Parameters

Name	Description
call_reject_reason	str or CallRejectReason The rejection reason. Default value: None

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError

resume_recording

Resume recording the call.

resume_recording(recording_id: str, **kwargs) -> None

Parameters

Name	Description
recording_id Required	str The recording id.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError

start_recording

start_recording(*, server_call_id: str, recording_state_callback_url: str | None = None, recording_content_type: str | 'RecordingContent' | None = None, recording_channel_type: str | 'RecordingChannel' | None = None, recording_format_type: str | 'RecordingFormat' | None = None, audio_channel_participant_ordering: List['CommunicationIdentifier'] | None = None, channel_affinity: List['ChannelAffinity'] | None = None, recording_storage: 'AzureCommunicationsRecordingStorage' | 'AzureBlobContainerRecordingStorage' | None = None, pause_on_start: bool | None = None, **kwargs) -> RecordingProperties

stop_recording

Stop recording the call.

stop_recording(recording_id: str, **kwargs) -> None

Parameters

Name	Description
recording_id Required	str The recording id.

Returns

Type	Description
None	None

Exceptions

Type	Description
HttpResponseError