azure.communication.chat.aio package¶

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

A client to interact with the AzureCommunicationService Chat gateway.

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

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.aio import ChatClient
from azure.communication.identity._shared.user_credential_async import CommunicationTokenCredential
from azure.communication.chat._shared.user_token_refresh_options import CommunicationTokenRefreshOptions

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

async close() → None [source]¶

async create_chat_thread(topic: str, **kwargs) → azure.communication.chat._models.CreateChatThreadResult[source]¶

Creates a chat thread.

Parameters

topic (str) – Required. The thread topic.

Keyword Arguments

thread_participants (list[ChatThreadParticipant]) – Optional. Participants to be added to the thread.
repeatability_request_id (str) – Optional. 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

CreateChatThreadResult

Return type

CreateChatThreadResult

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Creating ChatThreadClient by creating a new chat thread.¶

topic = "test topic"
participants = [ChatThreadParticipant(
    user=self.user,
    display_name='name',
    share_history_time=datetime.utcnow()
)]
# creates a new chat_thread everytime
create_chat_thread_result = await chat_client.create_chat_thread(topic, thread_participants=participants)

# creates a new chat_thread if not exists
repeatability_request_id = 'b66d6031-fdcc-41df-8306-e524c9f226b8'  # unique identifier
create_chat_thread_result_w_repeatability_id = await chat_client.create_chat_thread(
    topic,
    thread_participants=participants,
    repeatability_request_id=repeatability_request_id)

async delete_chat_thread(thread_id: str, **kwargs) → None [source]¶

Deletes a thread.

Parameters: thread_id (str) – Required. Thread id to delete.
Returns: None
Return type: None
Raises: ~azure.core.exceptions.HttpResponseError, ValueError

Example:

deleting chat thread.¶

await chat_client.delete_chat_thread(self._thread_id)

async get_chat_thread(thread_id: str, **kwargs) → azure.communication.chat._models.ChatThread[source]¶

Gets a chat thread.

Parameters: thread_id (str) – Required. Thread id to get.
Returns: ChatThread
Return type: ChatThread
Raises: ~azure.core.exceptions.HttpResponseError, ValueError

Example:

Getting a chat thread by thread id.¶

chat_thread = await chat_client.get_chat_thread(self._thread_id)

get_chat_thread_client(thread_id: str, **kwargs: Any) → azure.communication.chat.aio._chat_thread_client_async.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.aio import ChatClient
from azure.communication.identity._shared.user_credential_async import CommunicationTokenCredential
from azure.communication.chat._shared.user_token_refresh_options import 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: Any) → azure.core.async_paging.AsyncItemPaged[azure.communication.chat._generated.models._models_py3.ChatThreadInfo][source]¶

Gets the list of chat threads of a user.

Keyword Arguments

results_per_page (int) – The maximum number of chat threads to be 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

AsyncItemPaged[ChatThreadInfo]

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

listing chat threads.¶

from datetime import datetime, timedelta
import pytz
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.")
async for chat_thread_info_page in chat_thread_infos.by_page():
    async for chat_thread_info in chat_thread_info_page:
        print("thread id: ", chat_thread_info.id)

class azure.communication.chat.aio.ChatThreadClient(endpoint: str, credential: azure.communication.chat._shared.user_credential_async.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.aio import ChatClient
from azure.communication.chat import ChatThreadParticipant
from azure.communication.identity import CommunicationUserIdentifier
from azure.communication.identity._shared.user_credential_async import CommunicationTokenCredential
from azure.communication.chat._shared.user_token_refresh_options import CommunicationTokenRefreshOptions

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

async with chat_client:
    topic = "test topic"
    participants = [ChatThreadParticipant(
        user=self.user,
        display_name='name',
        share_history_time=datetime.utcnow()
    )]
    create_chat_thread_result = await chat_client.create_chat_thread(topic, thread_participants=participants)
    chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

async add_participant(thread_participant: azure.communication.chat._models.ChatThreadParticipant, **kwargs) → None [source]¶

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

If participant is added successfully, a tuple of (None, None) is expected. Failure to add participant to thread returns tuple of (thread_participant, communication_error).

Parameters: thread_participant (ChatThreadParticipant) – Required. Single thread participant to be added to the thread.
Returns: None
Return type: None
Raises: ~azure.core.exceptions.HttpResponseError, ValueError, RuntimeError

Example:

Adding single participant to chat thread.¶

decide_to_retry(error):
"""
Custom logic to decide whether to retry to add or not
"""
return True

c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    from azure.communication.chat import ChatThreadParticipant
    from datetime import datetime
    new_chat_thread_participant = ChatThreadParticipant(
            user=user,
            display_name='name',
            share_history_time=datetime.utcnow())
    try:
        await chat_thread_client.add_participant(new_chat_thread_participant)
    except RuntimeError as e:
        if e is not None and decide_to_retry(error=e):
            await chat_thread_client.add_participant(new_chat_thread_participant)

async add_participants(thread_participants: List[azure.communication.chat._models.ChatThreadParticipant], **kwargs) → [<class ‘azure.communication.chat._models.ChatThreadParticipant’>, <class ‘azure.communication.chat._generated.models._models_py3.CommunicationError’>][source]¶

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

If all participants are added successfully, then an empty list is returned; otherwise, a list of tuple(chat_thread_participant, communincation_error) is returned, of failed participants and its respective error

Parameters: thread_participants (list[ChatThreadParticipant]) – Required. Thread participants to be added to the thread.
Returns: List[(ChatThreadParticipant, CommunicationError)]
Return type: list((ChatThreadParticipant, CommunicationError))
Raises: ~azure.core.exceptions.HttpResponseError, ValueError, RuntimeError

Example:

Adding participants to chat thread.¶

decide_to_retry(error):
"""
Custom logic to decide whether to retry to add or not
"""
return True

c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    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]
    result = await chat_thread_client.add_participants(thread_participants)

    # list of participants which were unsuccessful to be added to chat thread
    retry = [p for p, e in result if decide_to_retry(e)]
    if len(retry) > 0:
        chat_thread_client.add_participants(retry)

async close() → None [source]¶

async delete_message(message_id: str, **kwargs) → None [source]¶

Deletes a message.

Parameters: message_id (str) – Required. The message id.
Returns: None
Return type: None
Raises: ~azure.core.exceptions.HttpResponseError, ValueError

Example:

Deleting a messages.¶

c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    # set `message_id` to an existing message id
    await chat_thread_client.delete_message(message_id)

async get_message(message_id: str, **kwargs) → azure.communication.chat._models.ChatMessage[source]¶

Gets a message by id.

Parameters: message_id (str) – Required. The message id.
Returns: ChatMessage
Return type: ChatMessage
Raises: ~azure.core.exceptions.HttpResponseError, ValueError

Example:

Getting a message by message id.¶

c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    # set `message_id` to an existing message id
    chat_message = await chat_thread_client.get_message(message_id)

    print("Message received: ChatMessage: content=", chat_message.content.message, ", id=", chat_message.id)

list_messages(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[azure.communication.chat._models.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.

Returns

An iterator like instance of ChatMessage

Return type

AsyncItemPaged[ChatMessage]

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Listing messages of a chat thread.¶

 datetime import datetime, timedelta
c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    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")
    async for chat_message_page in chat_messages.by_page():
        async for chat_message in chat_message_page:
            print("ChatMessage: message=", chat_message.content.message)

list_participants(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[azure.communication.chat._models.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.

Returns

An iterator like instance of ChatThreadParticipant

Return type

AsyncItemPaged[ChatThreadParticipant]

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Listing participants of chat thread.¶

c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    chat_thread_participants = chat_thread_client.list_participants()
    print("list_participants succeeded, participants:")
    async for chat_thread_participant_page in chat_thread_participants.by_page():
        async for chat_thread_participant in chat_thread_participant_page:
            print("ChatThreadParticipant: ", chat_thread_participant)

list_read_receipts(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[azure.communication.chat._models.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.

Returns

An iterator like instance of ChatMessageReadReceipt

Return type

AsyncItemPaged[ChatMessageReadReceipt]

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Listing read receipts.¶

c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    read_receipts = chat_thread_client.list_read_receipts()
    print("list_read_receipts succeeded, receipts:")
    async for read_receipt_page in read_receipts.by_page():
        async for read_receipt in read_receipt_page:
            print(read_receipt)

async remove_participant(user: azure.communication.chat._shared.models.CommunicationUserIdentifier, **kwargs) → None [source]¶

Remove a participant from a thread.

Parameters: user (CommunicationUserIdentifier) – Required. User identity of the thread participant to remove from the thread.
Returns: None
Return type: None
Raises: ~azure.core.exceptions.HttpResponseError, ValueError

Example:

Removing participant from chat thread.¶

 azure.communication.chat import ChatThreadParticipant
 azure.communication.identity import CommunicationUserIdentifier
 datetime import datetime

c with chat_client:
# create 2 new users using CommunicationIdentityClient.create_user method
user1 = identity_client.create_user()
user2 = identity_client.create_user()

# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)

async with chat_thread_client:
    # add user1 and user2 to chat thread
    participant1 = ChatThreadParticipant(
        user=user1,
        display_name='Fred Flinstone',
        share_history_time=datetime.utcnow())

    participant2 = ChatThreadParticipant(
        user=user2,
        display_name='Wilma Flinstone',
        share_history_time=datetime.utcnow())

    thread_participants = [participant1, participant2]
    await chat_thread_client.add_participants(thread_participants)

    # Option 1 : Iterate through all participants, find and delete Fred Flinstone
    chat_thread_participants = chat_thread_client.list_participants()

    async for chat_thread_participant_page in chat_thread_participants.by_page():
        async for chat_thread_participant in chat_thread_participant_page:
            print("ChatThreadParticipant: ", chat_thread_participant)
            if chat_thread_participant.user.identifier == user1.identifier:
                print("Found Fred!")
                await chat_thread_client.remove_participant(chat_thread_participant.user)
                print("Fred has been removed from the thread...")
                break

    # Option 2: Directly remove Wilma Flinstone
    unique_identifier = user2.identifier  # in real scenario the identifier would need to be retrieved from elsewhere
    await chat_thread_client.remove_participant(CommunicationUserIdentifier(unique_identifier))
    print("Wilma has been removed from the thread...")

async send_message(content: str, **kwargs) → 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.

Returns: str
Return type: str
Raises: ~azure.core.exceptions.HttpResponseError, ValueError

Example:

Sending a message.¶

 azure.communication.chat import ChatMessageType
c with chat_client:
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    # Scenario 1: Send message without specifying chat_message_type
    send_message_result_id = await chat_thread_client.send_message(
        "Hello! My name is Fred Flinstone",
        sender_display_name="Fred Flinstone")

    # Scenario 2: Send message specifying chat_message_type
    send_message_result_w_type_id = await chat_thread_client.send_message(
        "Hello! My name is Wilma Flinstone",
        sender_display_name="Wilma Flinstone",
        chat_message_type=ChatMessageType.TEXT)  # equivalent to setting chat_message_type='text'

    # Verify message content
    print("First Message:", (await chat_thread_client.get_message(send_message_result_id)).content.message)
    print("Second Message:", (await chat_thread_client.get_message(send_message_result_w_type_id)).content.message)

async send_read_receipt(message_id: str, **kwargs) → 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.
Returns: None
Return type: None
Raises: ~azure.core.exceptions.HttpResponseError, ValueError

Example:

Sending read receipt of a chat message.¶

c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    # set `message_id` to an existing message id
    await chat_thread_client.send_read_receipt(message_id)

async send_typing_notification(**kwargs) → None [source]¶

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

Returns: None
Return type: None
Raises: ~azure.core.exceptions.HttpResponseError, ValueError

Example:

Sending typing notification.¶

c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    await chat_thread_client.send_typing_notification()

async update_message(message_id: str, content: str = None, **kwargs) → None [source]¶

Updates a message.

Parameters

message_id (str) – Required. The message id.
content (str) – Chat message content.

Returns

None

Return type

None

Raises

~azure.core.exceptions.HttpResponseError, ValueError

Example:

Updating a sent messages.¶

c with chat_client:
# set `thread_id` to an existing thread id
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)
async with chat_thread_client:
    # set `message_id` to an existing message id
    previous_content = (await chat_thread_client.get_message(message_id)).content.message

    content = "updated message content"
    await chat_thread_client.update_message(self._message_id, content=content)

    current_content = (await chat_thread_client.get_message(message_id)).content.message

    print("Chat Message Updated: Previous value: ", previous_content, ", Current value: ", current_content)

async update_topic(topic: str = None, **kwargs) → 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.
Returns: None
Return type: None
Raises: ~azure.core.exceptions.HttpResponseError, ValueError

Example:

Updating chat thread.¶

t `thread_id` to an existing thread id
c with chat_client:
chat_thread = await chat_client.get_chat_thread(thread_id=thread_id)
previous_topic = chat_thread.topic
chat_thread_client = chat_client.get_chat_thread_client(thread_id=thread_id)

async with chat_thread_client:
    topic = "updated thread topic"
    await chat_thread_client.update_topic(topic=topic)

chat_thread = await chat_client.get_chat_thread(thread_id=thread_id)
updated_topic = chat_thread.topic
print("Chat Thread Topic Update: Previous value: ", previous_topic, ", Current value: ", updated_topic)

property thread_id¶

Gets the thread id from the client.

Return type: str