ChatThreadClient Class

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, chat_error) is returned, of failed participants and its respective error

add_participants(thread_participants: List[ChatParticipant], **kwargs: Any) -> List[Tuple[ChatParticipant, ChatError]]

Parameters

Returns

Exceptions

Examples

Adding participants to chat thread.

   from azure.communication.chat import ChatParticipant
   from datetime import datetime

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

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

   # create `user` using CommunicationIdentityClient.create_user method for new users;
   # else for existing users set `user` = CommunicationUserIdentifier(some_user_id)
   new_participant = ChatParticipant(
       identifier=user,
       display_name='name',
       share_history_time=datetime.utcnow())

   # create list containing one or more participants
   thread_participants = [new_participant]
   result = 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 retry:
       chat_thread_client.add_participants(retry)

close() -> None

Deletes a message.

delete_message(message_id: str, **kwargs: Any) -> None

Parameters

Returns

Exceptions

Examples

Deleting a message.

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

   # set `message_id` to an existing message id
   chat_thread_client.delete_message(message_id)

Gets a message by id.

get_message(message_id: str, **kwargs: Any) -> ChatMessage

Parameters

Returns

Exceptions

Examples

Retrieving a message by message id.

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

   # set `message_id` to an existing message id
   chat_message = chat_thread_client.get_message(message_id)

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

Gets the properties of the chat thread.

get_properties(**kwargs: Any) -> ChatThreadProperties

Returns

Exceptions

Examples

Retrieving chat thread properties by chat thread id.

   from azure.communication.chat import ChatClient, CommunicationTokenCredential

   # set `endpoint` to an existing ACS endpoint
   chat_client = ChatClient(endpoint, CommunicationTokenCredential(token))
   chat_thread_client = chat_client.get_chat_thread_client(thread_id)
   chat_thread_properties = chat_thread_client.get_properties()
   print('Expected Thread Id: ', thread_id, ' Actual Value: ', chat_thread_properties.id)

Gets a list of messages from a thread.

list_messages(**kwargs: Any) -> ItemPaged[ChatMessage]

Keyword-Only Parameters

Returns

Exceptions

Examples

Listing messages of a chat thread.

   from datetime import datetime, timedelta

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

   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():
       for chat_message in chat_message_page:
           print("ChatMessage: message=", chat_message.content.message)
           for attachment in chat_message.content.attachments:
               if attachment.type == "image":
                   print("image attachment: ", attachment.name, " with ID: ", attachment.id, "received.")
                   # render `attachment.preview_url` as the thumbnail
                   # render `attachment.url` as the full image
               elif attachment.type == "file":
                   print("file attachment: ", attachment.name, " with ID: ", attachment.id, "received.")
                   # render a button that will navigate user to the URL provided in `attachment.preview_url`

Gets the participants of a thread.

list_participants(**kwargs: Any) -> ItemPaged[ChatParticipant]

Keyword-Only Parameters

Returns

Exceptions

Examples

Listing participants of chat thread.

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

   chat_thread_participants = chat_thread_client.list_participants()

   for chat_thread_participant_page in chat_thread_participants.by_page():
       for chat_thread_participant in chat_thread_participant_page:
           print("ChatParticipant: ", chat_thread_participant)

Gets read receipts for a thread.

list_read_receipts(**kwargs: Any) -> ItemPaged[ChatMessageReadReceipt]

Keyword-Only Parameters

Returns

Exceptions

Examples

Listing read receipts.

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

   read_receipts = chat_thread_client.list_read_receipts()

   for read_receipt_page in read_receipts.by_page():
       for read_receipt in read_receipt_page:
           print(read_receipt)

Remove a participant from a thread.

remove_participant(identifier: CommunicationIdentifier, **kwargs: Any) -> None

Parameters

Returns

Exceptions

Examples

Removing participant from chat thread.

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

   for chat_thread_participant_page in chat_thread_participants.by_page():
       for chat_thread_participant in chat_thread_participant_page:
           print("ChatParticipant: ", chat_thread_participant)
           if chat_thread_participant.identifier.properties['id'] == user1.properties['id']:
               print("Found Fred!")
               chat_thread_client.remove_participant(chat_thread_participant.identifier)
               print("Fred has been removed from the thread...")
               break

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

Sends a message to a thread.

send_message(content: str, **kwargs: Any) -> SendChatMessageResult

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

Sending a message.

   from azure.communication.chat import ChatMessageType

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

   # Scenario 1: Send message without specifying chat_message_type
   send_message_result = chat_thread_client.send_message(
       "Hello! My name is Fred Flinstone",
       sender_display_name="Fred Flinstone")
   send_message_result_id = send_message_result.id

   # Scenario 2: Send message specifying chat_message_type
   send_message_result_w_type = 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'
   send_message_result_w_type_id = send_message_result_w_type.id
   # Verify message content
   print("First Message:", chat_thread_client.get_message(send_message_result_id).content.message)
   print("Second Message:", chat_thread_client.get_message(send_message_result_w_type_id).content.message)

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

send_read_receipt(message_id: str, **kwargs: Any) -> None

Parameters

Returns

Exceptions

Examples

Sending read receipt of a chat message.

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

   # set `message_id` to an existing message id
   chat_thread_client.send_read_receipt(message_id)

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

send_typing_notification(**kwargs: Any) -> None

Keyword-Only Parameters

Returns

Exceptions

Examples

Send typing notification.

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

   chat_thread_client.send_typing_notification()

Updates a message.

update_message(message_id: str, content: str | None = None, **kwargs: Any) -> None

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

Updating an already sent message.

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

   # set `message_id` to an existing message id
   previous_content = chat_thread_client.get_message(message_id).content.message
   content = "updated content"
   chat_thread_client.update_message(message_id, content=content)

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

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

Updates a thread's properties.

update_topic(topic: str | None = None, **kwargs: Any) -> None

Parameters

Returns

Exceptions

Examples

Updating chat thread.

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

   topic = "updated thread topic"
   chat_thread_client.update_topic(topic=topic)

   chat_thread_properties = chat_thread_client.get_properties()
   updated_topic = chat_thread_properties.topic
   print("Chat Thread Topic Update: Previous value: ", previous_topic, ", Current value: ", updated_topic)

Gets the thread id from the client.

Returns