Chat - Create Chat Thread

參考

Service:: Communication

API Version:: 2024-03-15-preview

建立聊天對話。

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

URI 參數

名稱	位於	必要	類型	Description
endpoint	path	True	string	Azure 通訊資源的端點。
api-version	query	True	string	要叫用的 API 版本。

要求標頭

名稱	必要	類型	Description
Authorization	True	string	ACS (Azure 通訊服務) 使用者存取令牌。
repeatability-request-id		string	如果指定，用戶端會指示要求可重複;也就是說，用戶端可以使用相同的 Repeatability-Request-Id 多次提出要求，並取得適當的回應，而不需要伺服器多次執行要求。 Repeatability-Request-Id 的值是不透明的字串，代表客戶端產生的全域唯一要求標識符。建議使用第 4 版 (隨機) UUID。

要求本文

名稱	必要	類型	Description
topic	True	string	聊天對話主題。
metadata		object	線程的內容元數據。元数据由名称/值对组成。所有元數據組的大小總計可以有 1 KB 的大小。
participants		ChatParticipant[]	要新增至聊天對話的參與者。
retentionPolicy		ChatRetentionPolicy: ThreadCreationDateRetentionPolicy NoneRetentionPolicy	自動刪除的數據保留原則。

回應

名稱	類型	Description
201 Created	CreateChatThreadResult	線程已建立， `Location` 標頭會包含新建立線程的URL。
401 Unauthorized	CommunicationErrorResponse	未經授權。
403 Forbidden	CommunicationErrorResponse	禁止。
429 Too Many Requests	CommunicationErrorResponse	太多要求。
Other Status Codes	CommunicationErrorResponse	服務無法使用。

安全性

Authorization

ACS (Azure 通訊服務) 使用者存取令牌。

Type: apiKey
In: header

範例

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

定義

名稱	Description
ChatParticipant	聊天對話的參與者。
ChatThreadProperties	聊天對話。
CreateChatThreadRequest	要求裝載以建立聊天對話。
CreateChatThreadResult	建立聊天對話作業的結果。
NoneRetentionPolicy	沒有線程保留原則。
ThreadCreationDateRetentionPolicy	根據線程建立日期的線程保留原則。

ChatParticipant

聊天對話的參與者。

名稱	類型	Description
communicationIdentifier	CommunicationIdentifierModel
displayName	string	聊天參與者的顯示名稱。
metadata	object	聊天參與者的內容元數據。元数据由名称/值对组成。所有元數據組的大小總計可以有 1 KB 的大小。
shareHistoryTime	string	與參與者共用聊天歷程記錄的時間。時間戳的格式為RFC3339： `yyyy-MM-ddTHH:mm:ssZ`。

ChatThreadProperties

聊天對話。

名稱	類型	Description
createdByCommunicationIdentifier	CommunicationIdentifierModel
createdOn	string	建立聊天對話時的時間戳。時間戳的格式為RFC3339： `yyyy-MM-ddTHH:mm:ssZ`。
deletedOn	string	刪除聊天對話時的時間戳。時間戳的格式為RFC3339： `yyyy-MM-ddTHH:mm:ssZ`。
id	string	聊天對話標識碼。
metadata	object	線程的內容元數據。元数据由名称/值对组成。所有元數據組的大小總計可以有 1 KB 的大小。
retentionPolicy	ChatRetentionPolicy: NoneRetentionPolicy ThreadCreationDateRetentionPolicy	自動刪除的數據保留原則。
topic	string	聊天對話主題。

CreateChatThreadRequest

要求裝載以建立聊天對話。

名稱	類型	Description
metadata	object	線程的內容元數據。元数据由名称/值对组成。所有元數據組的大小總計可以有 1 KB 的大小。
participants	ChatParticipant[]	要新增至聊天對話的參與者。
retentionPolicy	ChatRetentionPolicy: NoneRetentionPolicy ThreadCreationDateRetentionPolicy	自動刪除的數據保留原則。
topic	string	聊天對話主題。

CreateChatThreadResult

建立聊天對話作業的結果。

名稱	類型	Description
chatThread	ChatThreadProperties	聊天對話。
invalidParticipants	CommunicationError[]	無法新增至聊天對話的參與者。

NoneRetentionPolicy

沒有線程保留原則。

名稱	類型	Description
kind	string: none	保留原則類型

ThreadCreationDateRetentionPolicy

根據線程建立日期的線程保留原則。

名稱	類型	Description
deleteThreadAfterDays	integer	指出線程建立後的天數，將會刪除線程。
kind	string: threadCreationDate	保留原則類型

Share via

Chat - Create Chat Thread

URI 參數

要求標頭

要求本文

回應

安全性

Authorization

範例

Create chat thread

Sample Request

Sample Response

Create chat thread with repeatability request id header

Sample Request

Sample Response

定義

ChatParticipant

ChatThreadProperties

CreateChatThreadRequest

CreateChatThreadResult

NoneRetentionPolicy

ThreadCreationDateRetentionPolicy

其他資源