Chat - Create Chat Thread

Reference

Service:: Communication

API Version:: 2024-03-15-preview

Creates a chat thread.

POST {endpoint}/chat/threads?api-version=2024-03-15-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	The endpoint of the Azure Communication resource.
api-version	query	True	string	Version of API to invoke.

Request Header

Name	Required	Type	Description
Authorization	True	string	An ACS (Azure Communication Services) user access token.
repeatability-request-id		string	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. It is recommended to use version 4 (random) UUIDs.

Request Body

Name	Required	Type	Description
topic	True	string	The chat thread topic.
metadata		object	Contextual metadata for the thread. The metadata consists of name/value pairs. The total size of all metadata pairs can be up to 1KB in size.
participants		ChatParticipant[]	Participants to be added to the chat thread.
retentionPolicy		ChatRetentionPolicy: ThreadCreationDateRetentionPolicy NoneRetentionPolicy	Data retention policy for auto deletion.

Responses

Name	Type	Description
201 Created	CreateChatThreadResult	Thread created, the `Location` header would contain the URL for the newly created thread.
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

Create chat thread

Create chat thread with repeatability request id header

Create chat thread

Sample Request

HTTP

POST https://contoso.westus.communications.azure.com/chat/threads?api-version=2024-03-15-preview

{
  "topic": "Lunch",
  "retentionPolicy": {
    "kind": "threadCreationDate",
    "deleteThreadAfterDays": 30
  },
  "participants": [
    {
      "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"
        }
      },
      "displayName": "Jane"
    },
    {
      "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"
        }
      },
      "displayName": "Alex"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a"
        }
      },
      "displayName": "Bob"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b"
        }
      },
      "displayName": "Peter"
    }
  ]
}

Sample Response

Status code:: 201

Location: https://contoso.westus.communications.azure.com/chat/threads/19%3Auni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2

Response Body

{
  "chatThread": {
    "id": "19:uni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2",
    "topic": "Lunch",
    "createdOn": "2020-06-06T05:55:41.6460000Z",
    "createdByCommunicationIdentifier": {
      "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"
      }
    },
    "retentionPolicy": {
      "kind": "threadCreationDate",
      "deleteThreadAfterDays": 30
    }
  },
  "invalidParticipants": [
    {
      "target": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a",
      "code": "403",
      "message": "Permissions check failed"
    },
    {
      "target": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b",
      "code": "404",
      "message": "Not found"
    }
  ]
}

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."
  }
}

Create chat thread with repeatability request id header

Sample Request

HTTP

POST https://contoso.westus.communications.azure.com/chat/threads?api-version=2024-03-15-preview

{
  "topic": "Lunch",
  "participants": [
    {
      "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"
        }
      },
      "displayName": "Jane"
    },
    {
      "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"
        }
      },
      "displayName": "Alex"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a"
        }
      },
      "displayName": "Bob"
    },
    {
      "communicationIdentifier": {
        "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b",
        "communicationUser": {
          "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b"
        }
      },
      "displayName": "Peter"
    }
  ]
}

Sample Response

Status code:: 201

Location: https://contoso.westus.communications.azure.com/chat/threads/19%3Auni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2

Response Body

{
  "chatThread": {
    "id": "19:uni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2",
    "topic": "Lunch",
    "createdOn": "2020-06-06T05:55:41.6460000Z",
    "createdByCommunicationIdentifier": {
      "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"
      }
    }
  },
  "invalidParticipants": [
    {
      "target": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_a34d2d65-d72f-4c48-a12c-2d5c9ac75a1a",
      "code": "403",
      "message": "Permissions check failed"
    },
    {
      "target": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_f6762773-e33a-4727-985f-50bd1d197c7b",
      "code": "404",
      "message": "Not found"
    }
  ]
}

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
ChatParticipant	A participant of the chat thread.
ChatThreadProperties	Chat thread.
CreateChatThreadRequest	Request payload for creating a chat thread.
CreateChatThreadResult	Result of the create chat thread operation.
NoneRetentionPolicy	No thread retention policy.
ThreadCreationDateRetentionPolicy	Thread retention policy based on thread creation date.

ChatParticipant

A participant of the chat thread.

Name	Type	Description
communicationIdentifier	CommunicationIdentifierModel
displayName	string	Display name for the chat participant.
metadata	object	Contextual metadata for the chat participant. The metadata consists of name/value pairs. The total size of all metadata pairs can be up to 1KB in size.
shareHistoryTime	string	Time from which the chat history is shared with the participant. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.

ChatThreadProperties

Chat thread.

Name	Type	Description
createdByCommunicationIdentifier	CommunicationIdentifierModel
createdOn	string	The timestamp when the chat thread was created. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.
deletedOn	string	The timestamp when the chat thread was deleted. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.
id	string	Chat thread id.
metadata	object	Contextual metadata for the thread. The metadata consists of name/value pairs. The total size of all metadata pairs can be up to 1KB in size.
retentionPolicy	ChatRetentionPolicy: NoneRetentionPolicy ThreadCreationDateRetentionPolicy	Data retention policy for auto deletion.
topic	string	Chat thread topic.

CreateChatThreadRequest

Request payload for creating a chat thread.

Name	Type	Description
metadata	object	Contextual metadata for the thread. The metadata consists of name/value pairs. The total size of all metadata pairs can be up to 1KB in size.
participants	ChatParticipant[]	Participants to be added to the chat thread.
retentionPolicy	ChatRetentionPolicy: NoneRetentionPolicy ThreadCreationDateRetentionPolicy	Data retention policy for auto deletion.
topic	string	The chat thread topic.

CreateChatThreadResult

Result of the create chat thread operation.

Name	Type	Description
chatThread	ChatThreadProperties	Chat thread.
invalidParticipants	CommunicationError[]	The participants that failed to be added to the chat thread.

NoneRetentionPolicy

No thread retention policy.

Name	Type	Description
kind	string: none	Retention Policy Type

ThreadCreationDateRetentionPolicy

Thread retention policy based on thread creation date.

Name	Type	Description
deleteThreadAfterDays	integer	Indicates how many days after the thread creation the thread will be deleted.
kind	string: threadCreationDate	Retention Policy Type

Share via

Chat - Create Chat Thread

URI Parameters

Request Header

Request Body

Responses

Security

Authorization

Examples

Create chat thread

Sample Request

Sample Response

Create chat thread with repeatability request id header

Sample Request

Sample Response

Definitions

ChatParticipant

ChatThreadProperties

CreateChatThreadRequest

CreateChatThreadResult

NoneRetentionPolicy

ThreadCreationDateRetentionPolicy

Additional resources