通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Chat - Create Chat Thread

服务:
Communication
API 版本:
2025-03-15

创建聊天线程。

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

URI 参数

名称 在 必需 类型 说明
endpoint
 path True

string

Azure 通信资源的终结点。
api-version
 query True

string

要调用的 API 版本。

请求头

名称 必需 类型 说明
Authorization True

string

ACS（Azure 通信服务）用户访问令牌。
repeatability-request-id

string

如果指定，客户端将指示请求可重复;也就是说，客户端可以使用相同的可重复性-Request-Id 多次发出请求并返回适当的响应，而无需服务器多次执行请求。 Repeatability-Request-Id 的值是一个不透明的字符串，表示客户端生成、全局唯一的、请求的标识符。 建议使用版本 4（随机）UUID。

请求正文

名称 必需 类型 说明
topic True

string

聊天线程主题。
metadata

object

线程的上下文元数据。 元数据由名称/值对组成。 所有元数据对的总大小最多可为 1KB。
participants

ChatParticipant[]

要添加到聊天线程中的参与者。
retentionPolicy ChatRetentionPolicy:

用于自动删除的数据保留策略。

响应

名称 类型 说明
201 Created

CreateChatThreadResult

创建线程时，Location 标头将包含新创建的线程的 URL。
401 Unauthorized

CommunicationErrorResponse

未授权。
403 Forbidden

CommunicationErrorResponse

已禁止。
429 Too Many Requests

CommunicationErrorResponse

请求过多。
Other Status Codes

CommunicationErrorResponse

服务不可用。

安全性

Authorization

ACS（Azure 通信服务）用户访问令牌。

类型: apiKey
在: header

示例

Create chat thread
Create chat thread with repeatability request id header

Create chat thread

示例请求

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

{
  "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"
    }
  ]
}

示例响应

状态代码:
201 
Location: https://contoso.westus.communications.azure.com/chat/threads/19%3Auni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2
{
  "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"
    }
  ]
}
状态代码:
401 
{
  "error": {
    "code": "Unauthorized",
    "message": "Request is not authorized."
  }
}
状态代码:
403 
{
  "error": {
    "code": "Forbidden",
    "message": "User is not allowed to perform specified action."
  }
}
状态代码:
429 
{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded."
  }
}
状态代码:
503 
{
  "error": {
    "code": "ServiceUnavailable",
    "message": "The server is currently unable to handle the request."
  }
}

Create chat thread with repeatability request id header

示例请求

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

{
  "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"
    }
  ]
}

示例响应

状态代码:
201 
Location: https://contoso.westus.communications.azure.com/chat/threads/19%3Auni01_zbnh3nt2dfuffezc3sox7dog7wfhk6y5qe2rwlnfhlhdzirihdpq@thread.v2
{
  "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"
    }
  ]
}
状态代码:
401 
{
  "error": {
    "code": "Unauthorized",
    "message": "Request is not authorized."
  }
}
状态代码:
403 
{
  "error": {
    "code": "Forbidden",
    "message": "User is not allowed to perform specified action."
  }
}
状态代码:
429 
{
  "error": {
    "code": "TooManyRequests",
    "message": "Rate limit exceeded."
  }
}
状态代码:
503 
{
  "error": {
    "code": "ServiceUnavailable",
    "message": "The server is currently unable to handle the request."
  }
}

定义

名称 说明
ChatParticipant

聊天线程的参与者。
ChatThreadProperties

聊天线程。
CreateChatThreadRequest

请求用于创建聊天线程的有效负载。
CreateChatThreadResult

创建聊天线程操作的结果。
NoneRetentionPolicy

无线程保留策略。
ThreadCreationDateRetentionPolicy

基于线程创建日期的线程保留策略。

ChatParticipant

Object

聊天线程的参与者。

名称 类型 说明
communicationIdentifier

CommunicationIdentifierModel

displayName

string

聊天参与者的显示名称。
metadata

object

聊天参与者的上下文元数据。 元数据由名称/值对组成。 所有元数据对的总大小最多可为 1KB。
shareHistoryTime

string (date-time)

聊天历史记录与参与者共享的时间。 时间戳采用RFC3339格式：yyyy-MM-ddTHH:mm:ssZ。

ChatThreadProperties

Object

聊天线程。

名称 类型 说明
createdByCommunicationIdentifier

CommunicationIdentifierModel

createdOn

string (date-time)

创建聊天线程时的时间戳。 时间戳采用RFC3339格式：yyyy-MM-ddTHH:mm:ssZ。
deletedOn

string (date-time)

删除聊天线程时的时间戳。 时间戳采用RFC3339格式：yyyy-MM-ddTHH:mm:ssZ。
id

string

聊天线程 ID。
metadata

object

线程的上下文元数据。 元数据由名称/值对组成。 所有元数据对的总大小最多可为 1KB。
retentionPolicy ChatRetentionPolicy:

用于自动删除的数据保留策略。
topic

string

聊天线程主题。

CreateChatThreadRequest

Object

请求用于创建聊天线程的有效负载。

名称 类型 说明
metadata

object

线程的上下文元数据。 元数据由名称/值对组成。 所有元数据对的总大小最多可为 1KB。
participants

ChatParticipant[]

要添加到聊天线程中的参与者。
retentionPolicy ChatRetentionPolicy:

用于自动删除的数据保留策略。
topic

string

聊天线程主题。

CreateChatThreadResult

Object

创建聊天线程操作的结果。

名称 类型 说明
chatThread

ChatThreadProperties

聊天线程。
invalidParticipants

CommunicationError[]

未能添加到聊天线程的参与者。

NoneRetentionPolicy

Object

无线程保留策略。

名称 类型 说明
kind string:

none

保留策略类型

ThreadCreationDateRetentionPolicy

Object

基于线程创建日期的线程保留策略。

名称 类型 说明
deleteThreadAfterDays

integer (int32)

指示线程创建后将删除线程的天数。
kind string:

threadCreationDate

保留策略类型