azure.communication.chat package

class azure.communication.chat.ChatClient(endpoint: str, credential: CommunicationTokenCredential, **kwargs: Any)[source]

A client to interact with the AzureCommunicationService Chat gateway.

This client provides operations to create chat thread, delete chat thread, get chat thread by id, list chat threads, create chat thread client.

Parameters
  • endpoint (str) – The endpoint of the Azure Communication resource.

  • credential (CommunicationTokenCredential) – The credentials with which to authenticate.

Example:

Creating the ChatClient from a URL and token.
from azure.communication.chat import ChatClient, CommunicationTokenCredential, CommunicationTokenRefreshOptions
refresh_options = CommunicationTokenRefreshOptions(self.token)
chat_client = ChatClient(self.endpoint, CommunicationTokenCredential(refresh_options))
close()None[source]
create_chat_thread(topic: str, thread_participants: list[ChatThreadParticipant], repeatability_request_id: Optional[str] = None, **kwargs: Any) → ChatThreadClient[source]

Creates a chat thread.

Parameters
  • topic (str) – Required. The thread topic.

  • thread_participants (list[ChatThreadParticipant]) – Required. Participants to be added to the thread.

  • repeatability_request_id (str) – 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, globally unique for all time, identifier for the request. If not specified, a new unique id would be generated.

Returns

ChatThreadClient

Return type

ChatThreadClient

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Creating ChatThreadClient by creating a new chat thread.
from datetime import datetime
from azure.communication.chat import(
    ChatClient,
    CommunicationUserIdentifier,
    CommunicationTokenCredential,
    CommunicationTokenRefreshOptions
    ChatThreadParticipant
)

refresh_options = CommunicationTokenRefreshOptions(self.token)
chat_client = ChatClient(self.endpoint, CommunicationTokenCredential(refresh_options))

topic = "test topic"
participants = [ChatThreadParticipant(
    user=self.user,
    display_name='name',
    share_history_time=datetime.utcnow()
)]

# creates a new chat_thread everytime
chat_thread_client = chat_client.create_chat_thread(topic, participants)

# creates a new chat_thread if not exists
repeatability_request_id = 'b66d6031-fdcc-41df-8306-e524c9f226b8' # unique identifier
chat_thread_client_w_repeatability_id = chat_client.create_chat_thread(topic,
                                                                       participants,
                                                                       repeatability_request_id)
delete_chat_thread(thread_id: str, **kwargs: Any)None[source]

Deletes a thread.

Parameters

thread_id (str) – Required. Thread id to delete.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

None, or the result of cls(response)

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

deleting chat thread.
from azure.communication.chat import ChatClient, CommunicationTokenCredential, CommunicationTokenRefreshOptions

refresh_options = CommunicationTokenRefreshOptions(self.token)
chat_client = ChatClient(self.endpoint, CommunicationTokenCredential(refresh_options))
chat_client.delete_chat_thread(self._thread_id)
get_chat_thread(thread_id: str, **kwargs: Any) → ChatThread[source]

Gets a chat thread.

Parameters

thread_id (str) – Required. Thread id to get.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

ChatThread, or the result of cls(response)

Return type

ChatThread

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Getting a chat thread by thread id.
from azure.communication.chat import ChatClient, CommunicationTokenCredential, CommunicationTokenRefreshOptions

refresh_options = CommunicationTokenRefreshOptions(self.token)
chat_client = ChatClient(self.endpoint, CommunicationTokenCredential(refresh_options))
chat_thread = chat_client.get_chat_thread(self._thread_id)
get_chat_thread_client(thread_id: str, **kwargs: Any) → ChatThreadClient[source]

Get ChatThreadClient by providing a thread_id.

Parameters

thread_id (str) – Required. The thread id.

Returns

ChatThreadClient

Return type

ChatThreadClient

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Creating the ChatThreadClient from an existing chat thread id.
from azure.communication.chat import ChatClient, CommunicationTokenCredential, CommunicationTokenRefreshOptions

refresh_options = CommunicationTokenRefreshOptions(self.token)
chat_client = ChatClient(self.endpoint, CommunicationTokenCredential(refresh_options))
chat_thread_client = chat_client.get_chat_thread_client(self._thread_id)
list_chat_threads(**kwargs) → ItemPaged[ChatThreadInfo][source]

Gets the list of chat threads of a user.

Keyword Arguments
  • results_per_page (int) – The maximum number of chat threads returned per page.

  • start_time (datetime) – The earliest point in time to get chat threads up to.

Returns

An iterator like instance of ChatThreadInfo

Return type

ItemPaged[ChatThreadInfo]

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

listing chat threads.
from azure.communication.chat import ChatClient, CommunicationTokenCredential, CommunicationTokenRefreshOptions
from datetime import datetime, timedelta
import pytz

refresh_options = CommunicationTokenRefreshOptions(self.token)
chat_client = ChatClient(self.endpoint, CommunicationTokenCredential(refresh_options))
start_time = datetime.utcnow() - timedelta(days=2)
start_time = start_time.replace(tzinfo=pytz.utc)
chat_thread_infos = chat_client.list_chat_threads(results_per_page=5, start_time=start_time)

print("list_threads succeeded with results_per_page is 5, and were created since 2 days ago.")
for info in chat_thread_infos:
    print("thread id:", info.id)
class azure.communication.chat.ChatThreadClient(endpoint: str, credential: CommunicationTokenCredential, thread_id: str, **kwargs: Any)[source]

A client to interact with the AzureCommunicationService Chat gateway. Instances of this class is normally created by ChatClient.create_chat_thread()

This client provides operations to add participant to chat thread, remove participant from chat thread, send message, delete message, update message, send typing notifications, send and list read receipt

Variables

thread_id (str) – Chat thread id.

Parameters
  • endpoint (str) – The endpoint of the Azure Communication resource.

  • credential (CommunicationTokenCredential) – The credentials with which to authenticate. The value contains a User Access Token

  • thread_id (str) – The unique thread id.

Example:

Creating the ChatThreadClient.
from datetime import datetime
from azure.communication.chat import (
    ChatClient,
    CommunicationUserIdentifier,
    CommunicationTokenCredential,
    CommunicationTokenRefreshOptions,
    ChatThreadParticipant
)
refresh_options = CommunicationTokenRefreshOptions(self.token)
chat_client = ChatClient(self.endpoint, CommunicationTokenCredential(refresh_options))
topic = "test topic"
participants = [ChatThreadParticipant(
    user=self.user,
    display_name='name',
    share_history_time=datetime.utcnow()
)]
chat_thread_client = chat_client.create_chat_thread(topic, participants)
add_participant(thread_participant: ChatThreadParticipant, **kwargs: Any)None[source]

Adds single thread participant to a thread. If participant already exist, no change occurs.

Parameters

thread_participant (ChatThreadParticipant) – Required. Single thread participant to be added to the thread.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

None, or the result of cls(response)

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Adding single participant to chat thread.
from azure.communication.chat import ChatThreadParticipant
from datetime import datetime
new_chat_thread_participant = ChatThreadParticipant(
        user=self.new_user,
        display_name='name',
        share_history_time=datetime.utcnow())
chat_thread_client.add_participant(new_chat_thread_participant)
add_participants(thread_participants: list[ChatThreadParticipant], **kwargs: Any)None[source]

Adds thread participants to a thread. If participants already exist, no change occurs.

Parameters

thread_participants (list[ChatThreadParticipant]) – Required. Thread participants to be added to the thread.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

None, or the result of cls(response)

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Adding participants to chat thread.
from azure.communication.chat import ChatThreadParticipant
from datetime import datetime
new_participant = ChatThreadParticipant(
        user=self.new_user,
        display_name='name',
        share_history_time=datetime.utcnow())
thread_participants = [new_participant]
chat_thread_client.add_participants(thread_participants)
close()None[source]
delete_message(message_id: str, **kwargs: Any)None[source]

Deletes a message.

Parameters

message_id (str) – Required. The message id.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

None, or the result of cls(response)

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Deleting a messages.
chat_thread_client.delete_message(self._message_id)
get_message(message_id: str, **kwargs: Any) → ChatMessage[source]

Gets a message by id.

Parameters

message_id (str) – Required. The message id.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

ChatMessage, or the result of cls(response)

Return type

ChatMessage

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Getting a message by message id.
chat_message = chat_thread_client.get_message(self._message_id)
list_messages(**kwargs: Any) → ItemPaged[ChatMessage][source]

Gets a list of messages from a thread.

Keyword Arguments
  • results_per_page (int) – The maximum number of messages to be returned per page.

  • start_time (datetime) – The start time where the range query.

  • cls (callable) – A custom type or function that will be passed the direct response

Returns

An iterator like instance of ChatMessage

Return type

ItemPaged[ChatMessage]

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Listing messages of a chat thread.
from datetime import datetime, timedelta
start_time = datetime.utcnow() - timedelta(days=1)
chat_messages = chat_thread_client.list_messages(results_per_page=1, start_time=start_time)

print("list_messages succeeded with results_per_page is 1, and start time is yesterday UTC")
for chat_message_page in chat_messages.by_page():
    l = list(chat_message_page)
    print("page size: ", len(l))
list_participants(**kwargs: Any) → ItemPaged[ChatThreadParticipant][source]

Gets the participants of a thread.

Keyword Arguments
  • results_per_page (int) – The maximum number of participants to be returned per page.

  • skip (int) – Skips participants up to a specified position in response.

  • cls (callable) – A custom type or function that will be passed the direct response

Returns

An iterator like instance of ChatThreadParticipant

Return type

ItemPaged[ChatThreadParticipant]

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Listing participants of chat thread.
chat_thread_participants = chat_thread_client.list_participants()
print("list_chat_participants succeeded, participants: ")
for chat_thread_participant in chat_thread_participants:
    print(chat_thread_participant)
list_read_receipts(**kwargs: Any) → ItemPaged[ChatMessageReadReceipt][source]

Gets read receipts for a thread.

Keyword Arguments
  • results_per_page (int) – The maximum number of chat message read receipts to be returned per page.

  • skip (int) – Skips chat message read receipts up to a specified position in response.

  • cls (callable) – A custom type or function that will be passed the direct response

Returns

An iterator like instance of ChatMessageReadReceipt

Return type

ItemPaged[ChatMessageReadReceipt]

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Listing read receipts.
read_receipts = chat_thread_client.list_read_receipts()
print("list_read_receipts succeeded, receipts:")
for read_receipt in read_receipts:
    print(read_receipt)
remove_participant(user: CommunicationUserIdentifier, **kwargs: Any)None[source]

Remove a participant from a thread.

Parameters

user (CommunicationUserIdentifier) – Required. User identity of the thread participant to remove from the thread.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

None, or the result of cls(response)

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Removing participant from chat thread.
chat_thread_client.remove_participant(self.new_user)
send_message(content: str, **kwargs: Any)str[source]

Sends a message to a thread.

Parameters
  • content (str) – Required. Chat message content.

  • chat_message_type – The chat message type. Possible values include: “text”, “html”.

Default: ChatMessageType.TEXT :type chat_message_type: str or ~azure.communication.chat.models.ChatMessageType :keyword str sender_display_name: The display name of the message sender. This property is used to

populate sender name for push notifications.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

str, or the result of cls(response)

Return type

str

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Sending a message.
from azure.communication.chat import ChatMessagePriority

content = 'hello world'
sender_display_name = 'sender name'

send_message_result_id = chat_thread_client.send_message(
    content,
    sender_display_name=sender_display_name)

send_message_result_w_type_id = chat_thread_client.send_message(
    content,
    sender_display_name=sender_display_name, chat_message_type=ChatMessageType.TEXT)
send_read_receipt(message_id: str, **kwargs: Any)None[source]

Posts a read receipt event to a thread, on behalf of a user.

Parameters

message_id (str) – Required. Id of the latest message read by current user.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

None, or the result of cls(response)

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Sending read receipt of a chat message.
chat_thread_client.send_read_receipt(self._message_id)
send_typing_notification(**kwargs: Any)None[source]

Posts a typing event to a thread, on behalf of a user.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

None, or the result of cls(response)

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Sending typing notification.
chat_thread_client.send_typing_notification()
update_message(message_id: str, content: Optional[str] = None, **kwargs: Any)None[source]

Updates a message.

Parameters
  • message_id (str) – Required. The message id.

  • content (str) – Chat message content.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

None, or the result of cls(response)

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Updating a sent messages.
content = "updated content"
chat_thread_client.update_message(self._message_id, content=content)
update_topic(topic: Optional[str] = None, **kwargs: Any)None[source]

Updates a thread’s properties.

Parameters

topic (str) – Thread topic. If topic is not specified, the update will succeeded but chat thread properties will not be changed.

Keyword Arguments

cls (callable) – A custom type or function that will be passed the direct response

Returns

None, or the result of cls(response)

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Updating chat thread.
topic = "updated thread topic"
chat_thread_client.update_topic(topic=topic)
property thread_id

Gets the thread id from the client.

Return type

str

class azure.communication.chat.ChatMessage(**kwargs: Any)[source]

Chat message.

Variables are only populated by the server, and will be ignored when sending a request.

Variables
  • id (str) – The id of the chat message. This id is server generated.

  • type – Type of the chat message. Possible values include: “text”, “html”, “topicUpdated”, “participantAdded”, “participantRemoved”.

  • sequence_id – Sequence of the chat message in the conversation.

  • version (str) – Version of the chat message.

  • content – Content of the chat message.

  • sender_display_name – The display name of the chat message sender. This property is used to populate sender name for push notifications.

  • created_on – The timestamp when the chat message arrived at the server. The timestamp is in RFC3339 format: yyyy-MM-ddTHH:mm:ssZ.

  • sender_id – The chat message sender.

  • deleted_on – The timestamp when the chat message was deleted. The timestamp is in RFC3339 format: yyyy-MM-ddTHH:mm:ssZ.

  • edited_on – The last timestamp (if applicable) when the message was edited. The timestamp is in RFC3339 format: yyyy-MM-ddTHH:mm:ssZ.

class azure.communication.chat.ChatMessageContent(**kwargs: Any)[source]

Content of a chat message.

Parameters
  • message (str) – Chat message content for messages of types text or html.

  • topic (str) – Chat message content for messages of type topicUpdated.

  • participants (list[ChatParticipant]) – Chat message content for messages of types participantAdded or participantRemoved.

  • initiator (str) – Chat message content for messages of types participantAdded or participantRemoved.

class azure.communication.chat.ChatMessageReadReceipt(**kwargs: Any)[source]

A chat message read receipt indicates the time a chat message was read by a recipient.

Variables are only populated by the server, and will be ignored when sending a request.

Variables
  • sender – Read receipt sender.

  • chat_message_id (str) – Id for the chat message that has been read. This id is generated by the server.

  • read_on (datetime) – Read receipt timestamp. The timestamp is in ISO8601 format: yyyy-MM- ddTHH:mm:ssZ.

class azure.communication.chat.SendChatMessageResult(*, id: str, **kwargs)[source]

Result of the send message operation.

All required parameters must be populated in order to send to Azure.

Parameters

id (str) – Required. A server-generated message id.

as_dict(keep_readonly=True, key_transformer=<function attribute_transformer>, **kwargs)

Return a dict that can be JSONify using json.dump.

Advanced usage might optionaly use a callback as parameter:

Key is the attribute name used in Python. Attr_desc is a dict of metadata. Currently contains ‘type’ with the msrest type and ‘key’ with the RestAPI encoded key. Value is the current value in this object.

The string returned will be used to serialize the key. If the return type is a list, this is considered hierarchical result dict.

See the three examples in this file:

  • attribute_transformer

  • full_restapi_key_transformer

  • last_restapi_key_transformer

If you want XML serialization, you can pass the kwargs is_xml=True.

Parameters

key_transformer (function) – A key transformer function.

Returns

A dict JSON compatible object

Return type

dict

classmethod deserialize(data, content_type=None)

Parse a str using the RestAPI syntax and return a model.

Parameters
  • data (str) – A str using RestAPI structure. JSON by default.

  • content_type (str) – JSON by default, set application/xml if XML.

Returns

An instance of this model

Raises

DeserializationError if something went wrong

classmethod enable_additional_properties_sending()
classmethod from_dict(data, key_extractors=None, content_type=None)

Parse a dict using given key extractor return a model.

By default consider key extractors (rest_key_case_insensitive_extractor, attribute_key_case_insensitive_extractor and last_rest_key_case_insensitive_extractor)

Parameters
  • data (dict) – A dict using RestAPI structure

  • content_type (str) – JSON by default, set application/xml if XML.

Returns

An instance of this model

Raises

DeserializationError if something went wrong

classmethod is_xml_model()
serialize(keep_readonly=False, **kwargs)

Return the JSON that would be sent to azure from this model.

This is an alias to as_dict(full_restapi_key_transformer, keep_readonly=False).

If you want XML serialization, you can pass the kwargs is_xml=True.

Parameters

keep_readonly (bool) – If you want to serialize the readonly attributes

Returns

A dict JSON compatible object

Return type

dict

validate()

Validate this model recursively and return a list of ValidationError.

Returns

A list of validation error

Return type

list

class azure.communication.chat.ChatThread(**kwargs: Any)[source]

ChatThread.

Variables are only populated by the server, and will be ignored when sending a request.

Variables
  • id (str) – Chat thread id.

  • created_on (datetime) – The timestamp when the chat thread was created. The timestamp is in ISO8601 format: yyyy-MM-ddTHH:mm:ssZ.

  • created_by (CommunicationUserIdentifier) – the chat thread owner.

Parameters
class azure.communication.chat.ChatThreadInfo(*, id: str, topic: str, deleted_on: Optional[datetime.datetime] = None, **kwargs)[source]

Summary information of a chat thread.

Variables are only populated by the server, and will be ignored when sending a request.

All required parameters must be populated in order to send to Azure.

Parameters
  • id (str) – Required. Chat thread id.

  • topic (str) – Required. Chat thread topic.

  • deleted_on (datetime) – The timestamp when the chat thread was deleted. The timestamp is in RFC3339 format: yyyy-MM-ddTHH:mm:ssZ.

Variables

last_message_received_on (datetime) – The timestamp when the last message arrived at the server. The timestamp is in RFC3339 format: yyyy-MM-ddTHH:mm:ssZ.

as_dict(keep_readonly=True, key_transformer=<function attribute_transformer>, **kwargs)

Return a dict that can be JSONify using json.dump.

Advanced usage might optionaly use a callback as parameter:

Key is the attribute name used in Python. Attr_desc is a dict of metadata. Currently contains ‘type’ with the msrest type and ‘key’ with the RestAPI encoded key. Value is the current value in this object.

The string returned will be used to serialize the key. If the return type is a list, this is considered hierarchical result dict.

See the three examples in this file:

  • attribute_transformer

  • full_restapi_key_transformer

  • last_restapi_key_transformer

If you want XML serialization, you can pass the kwargs is_xml=True.

Parameters

key_transformer (function) – A key transformer function.

Returns

A dict JSON compatible object

Return type

dict

classmethod deserialize(data, content_type=None)

Parse a str using the RestAPI syntax and return a model.

Parameters
  • data (str) – A str using RestAPI structure. JSON by default.

  • content_type (str) – JSON by default, set application/xml if XML.

Returns

An instance of this model

Raises

DeserializationError if something went wrong

classmethod enable_additional_properties_sending()
classmethod from_dict(data, key_extractors=None, content_type=None)

Parse a dict using given key extractor return a model.

By default consider key extractors (rest_key_case_insensitive_extractor, attribute_key_case_insensitive_extractor and last_rest_key_case_insensitive_extractor)

Parameters
  • data (dict) – A dict using RestAPI structure

  • content_type (str) – JSON by default, set application/xml if XML.

Returns

An instance of this model

Raises

DeserializationError if something went wrong

classmethod is_xml_model()
serialize(keep_readonly=False, **kwargs)

Return the JSON that would be sent to azure from this model.

This is an alias to as_dict(full_restapi_key_transformer, keep_readonly=False).

If you want XML serialization, you can pass the kwargs is_xml=True.

Parameters

keep_readonly (bool) – If you want to serialize the readonly attributes

Returns

A dict JSON compatible object

Return type

dict

validate()

Validate this model recursively and return a list of ValidationError.

Returns

A list of validation error

Return type

list

class azure.communication.chat.CommunicationTokenCredential(communication_token_refresh_options)[source]

Credential type used for authenticating to an Azure Communication service. :param communication_token_refresh_options: The token used to authenticate to an Azure Communication service :type communication_token_refresh_options: ~azure.communication.chat.CommunicationTokenRefreshOptions

get_token()[source]

The value of the configured token. :rtype: ~azure.core.credentials.AccessToken

ON_DEMAND_REFRESHING_INTERVAL_MINUTES = 2
class azure.communication.chat.CommunicationTokenRefreshOptions[source]

Options for refreshing CommunicationTokenCredential. :param str token: The token used to authenticate to an Azure Communication service :param token_refresher: The token refresher to provide capacity to fetch fresh token :raises: TypeError

get_token()[source]

Return the the serialized JWT token.

get_token_refresher()[source]

Return the token refresher to provide capacity to fetch fresh token.

class azure.communication.chat.CommunicationUserIdentifier(identifier)[source]

Represents a user in Azure Communication Service. :ivar identifier: Communication user identifier. :vartype identifier: str :param identifier: Identifier to initialize CommunicationUserIdentifier. :type identifier: str

class azure.communication.chat.ChatThreadParticipant(**kwargs: Any)[source]

A participant of the chat thread.

All required parameters must be populated in order to send to Azure.

Parameters
  • user (CommunicationUserIdentifier) – Required. The CommunicationUserIdentifier.

  • display_name (str) – Display name for the chat thread participant.

  • share_history_time (datetime) – Time from which the chat history is shared with the participant. The timestamp is in ISO8601 format: yyyy-MM-ddTHH:mm:ssZ.

class azure.communication.chat.ChatMessageType[source]

The chat message type.

HTML = 'html'
PARTICIPANT_ADDED = 'participantAdded'
PARTICIPANT_REMOVED = 'participantRemoved'
TEXT = 'text'
TOPIC_UPDATED = 'topicUpdated'