Chat Thread - List Chat Messages

Reference

Service:: Communication

API Version:: 2024-03-07

Gets a list of messages from a thread.

GET {endpoint}/chat/threads/{chatThreadId}/messages?api-version=2024-03-07

With optional parameters:

GET {endpoint}/chat/threads/{chatThreadId}/messages?maxPageSize={maxPageSize}&startTime={startTime}&api-version=2024-03-07

URI Parameters

Name	In	Required	Type	Description
chatThreadId	path	True	string	The thread id of the message.
endpoint	path	True	string	The endpoint of the Azure Communication resource.
api-version	query	True	string	Version of API to invoke.
maxPageSize	query		integer int32	The maximum number of messages to be returned per page.
startTime	query		string date-time	The earliest point in time to get messages up to. The timestamp should be in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.

Request Header

Name	Required	Type	Description
Authorization	True	string	An ACS (Azure Communication Services) user access token.

Responses

Name	Type	Description
200 OK	ChatMessagesCollection	Success
401 Unauthorized	CommunicationErrorResponse	Unauthorized.
403 Forbidden	CommunicationErrorResponse	Forbidden.
429 Too Many Requests	CommunicationErrorResponse	Too many requests.
Other Status Codes	CommunicationErrorResponse	Service unavailable.

Security

Authorization

An ACS (Azure Communication Services) user access token.

Type: apiKey
In: header

Examples

Get messages with pagination (max page size)

Sample Request

HTTP

GET https://contoso.westus.communications.azure.com/chat/threads/19:453dafb77b26481ea2e73bcada0324af@thread.v2/messages?maxPageSize=5&api-version=2024-03-07

Sample Response

Status code:: 200

{
  "value": [
    {
      "id": "1593107077690",
      "type": "text",
      "version": "1593107077683",
      "sequenceId": "5",
      "content": {
        "message": "So where should we get lunch from today?"
      },
      "senderDisplayName": "Jane",
      "createdOn": "2020-06-25T17:44:37.6830000Z",
      "senderCommunicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b"
        }
      }
    },
    {
      "id": "1593107077683",
      "type": "text",
      "sequenceId": "4",
      "version": "1593107077683",
      "content": {
        "message": "Let's use this chat to decide what to get for lunch today."
      },
      "senderDisplayName": "Jane",
      "createdOn": "2020-06-25T17:44:37.6830000Z",
      "senderCommunicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b"
        }
      }
    },
    {
      "id": "1593107046498",
      "type": "text",
      "sequenceId": "3",
      "version": "1593107046498",
      "content": {
        "message": "Good morning everyone!"
      },
      "senderDisplayName": "Jane",
      "createdOn": "2020-06-25T17:44:06.4980000Z",
      "senderCommunicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b"
        }
      }
    },
    {
      "id": "1593106976785",
      "type": "topicUpdated",
      "sequenceId": "2",
      "version": "1593106976785",
      "content": {
        "initiatorCommunicationIdentifier": {
          "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b",
          "communicationUser": {
            "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b"
          }
        },
        "topic": "Lunch"
      },
      "createdOn": "2020-06-25T17:42:56.7850000Z"
    },
    {
      "id": "1593106976753",
      "type": "participantAdded",
      "version": "1593106976753",
      "sequenceId": "1",
      "content": {
        "initiatorCommunicationIdentifier": {
          "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b",
          "communicationUser": {
            "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b"
          }
        },
        "participants": [
          {
            "communicationIdentifier": {
              "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b",
              "communicationUser": {
                "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_0e59221d-0c1d-46ae-9544-c963ce56c10b"
              }
            }
          },
          {
            "communicationIdentifier": {
              "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715",
              "communicationUser": {
                "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
              }
            }
          },
          {
            "communicationIdentifier": {
              "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f13a9208-0bb8-45c0-916c-f3ed922728ce",
              "communicationUser": {
                "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f13a9208-0bb8-45c0-916c-f3ed922728ce"
              }
            }
          }
        ]
      },
      "createdOn": "2020-06-25T17:42:56.7530000Z"
    }
  ],
  "nextLink": "https://contoso.westus.communications.azure.com/chat/threads/19:453dafb77b26481ea2e73bcada0324af@thread.v2/messages?syncState=3e4700000031393a756e6930315f7a626e68336e74326466756666657a6333736f7837646f67377766686b36793571653272776c6e66686c68647a69726968647071407468726561642e763201451fe6e77201000004357fea72010000&startTime=0&maxPageSize=5&api-version=2024-03-07"
}

Status code:: 401

{
  "error": {
    "code": "Unauthorized",
    "message": "Request is not authorized."
  }
}

Status code:: 403

{
  "error": {
    "code": "Forbidden",
    "message": "User is not allowed to perform specified action."
  }
}

Status code:: 429

{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded."
  }
}

Status code:: 503

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "The server is currently unable to handle the request."
  }
}

Definitions

Name	Description
ChatAttachment	An attachment in a chat message.
ChatAttachmentType	The type of attachment.
ChatMessage	Chat message.
ChatMessageContent	Content of a chat message.
ChatMessagesCollection	Collection of chat messages for a particular chat thread.
ChatMessageType	The chat message type.
ChatParticipant	A participant of the chat thread.

ChatAttachment

An attachment in a chat message.

Name	Type	Description
attachmentType	ChatAttachmentType	The type of attachment.
id	string	Id of the attachment
name	string	The name of the attachment content.
previewUrl	string	The URL where the preview of attachment can be downloaded
url	string	The URL where the attachment can be downloaded

ChatAttachmentType

The type of attachment.

Name	Type	Description
file	string
image	string

ChatMessage

Chat message.

Name	Type	Description
content	ChatMessageContent	Content of a chat message.
createdOn	string	The timestamp when the chat message arrived at the server. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.
deletedOn	string	The timestamp (if applicable) when the message was deleted. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.
editedOn	string	The last timestamp (if applicable) when the message was edited. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.
id	string	The id of the chat message. This id is server generated.
metadata	object	Message metadata.
senderCommunicationIdentifier	CommunicationIdentifierModel
senderDisplayName	string	The display name of the chat message sender. This property is used to populate sender name for push notifications.
sequenceId	string	Sequence of the chat message in the conversation.
type	ChatMessageType	The chat message type.
version	string	Version of the chat message.

ChatMessageContent

Content of a chat message.

Name	Type	Description
attachments	ChatAttachment[]	List of attachments for this message
initiatorCommunicationIdentifier	CommunicationIdentifierModel
message	string	Chat message content for messages of types text or html.
participants	ChatParticipant[]	Chat message content for messages of types participantAdded or participantRemoved.
topic	string	Chat message content for messages of type topicUpdated.

ChatMessagesCollection

Collection of chat messages for a particular chat thread.

Name	Type	Description
nextLink	string	If there are more chat messages that can be retrieved, the next link will be populated.
value	ChatMessage[]	Collection of chat messages.

ChatMessageType

The chat message type.

Name	Type	Description
html	string
participantAdded	string
participantRemoved	string
text	string
topicUpdated	string

ChatParticipant

A participant of the chat thread.

Name	Type	Description
communicationIdentifier	CommunicationIdentifierModel
displayName	string	Display name for the chat participant.
shareHistoryTime	string	Time from which the chat history is shared with the participant. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.