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

快速入门：向应用中添加聊天

项目
04/03/2023

从 Azure 通信服务着手，方法是使用通信服务聊天 SDK 向应用程序添加实时聊天。在本快速入门中，我们将使用聊天 SDK 创建聊天会话，使用户能够彼此进行对话。若要了解有关聊天概念的详细信息，请访问聊天概念文档。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
活动的通信服务资源和连接字符串。创建通信服务资源。
安装 Azure CLI。
记下通信服务资源终结点。可从 Azure 门户获取此终结点。或者，可以在连接字符串中找到终结点 URL。它是在 endpoint= 之后并以 https:// 开头的 URL。
用户访问令牌。请确保将范围设置为“聊天”，并记下令牌字符串和 user_id 字符串。还可以使用 Azure CLI，并结合你的连接字符串运行以下命令来创建用户和访问令牌。
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
有关详细信息，请参阅使用 Azure CLI 创建和管理访问令牌。

设置

添加扩展

使用 az extension 命令为 Azure CLI 添加 Azure 通信服务扩展。

az extension add --name communication

需要登录到 Azure CLI。可以从终端运行 az login 命令并提供凭据进行登录。

（可选）使用 Azure CLI 标识操作，而无需传入终结点或访问令牌

将终结点存储在环境变量中

可以配置 AZURE_COMMUNICATION_ENDPOINT 环境变量来使用 Azure CLI 聊天操作，而无需使用 --endpoint 来传入终结点。若要配置环境变量，请打开控制台窗口，然后从以下选项卡中选择操作系统。将 <yourEndpoint> 替换为实际终结点。

打开控制台窗口并输入以下命令：

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

添加环境变量后，可能需要重启任何正在运行的、需要读取环境变量的程序（包括控制台窗口）。例如，如果使用 Visual Studio 作为编辑器，请在运行示例之前重启 Visual Studio。

编辑 .zshrc，然后添加环境变量：

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

添加环境变量后，请从控制台窗口运行 source ~/.zshrc，使更改生效。如果在 IDE 打开的情况下创建了环境变量，则可能需要关闭编辑器、IDE 或 shell，然后再重新打开才能访问该变量。

编辑 .bash_profile，然后添加环境变量：

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

添加环境变量后，请从控制台窗口运行 source ~/.bash_profile，使更改生效。如果在 IDE 打开的情况下创建了环境变量，则可能需要关闭编辑器、IDE 或 shell，然后再重新打开才能访问该变量。

在环境变量中存储你的访问令牌

可以配置 AZURE_COMMUNICATION_ACCESS_TOKEN 环境变量来使用 Azure CLI 聊天操作，而无需使用 --access-token 来传入访问令牌。若要配置环境变量，请打开控制台窗口，然后从以下选项卡中选择操作系统。将 <yourAccessToken> 替换为你的实际访问令牌。

打开控制台窗口并输入以下命令：

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

编辑 .zshrc，然后添加环境变量：

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

编辑 .bash_profile，然后添加环境变量：

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Operations

启动聊天会话

使用 thread create 命令创建聊天会话。

az communication chat thread create --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"

如果已将终结点和访问令牌存储在上述环境变量中，则无需将它们传递给命令。

az communication chat thread create --topic "<chatTopic>"

使用 <chatTopic> 指定一个会话主题。使用 thread update-topic 命令创建聊天会话后，可更新主题。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

更新聊天会话的主题

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"

将 <chatThreadId> 替换为聊天会话 ID。
将 <chatTopic> 替换为要设置的新聊天主题。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

列出所有聊天会话

thread list 命令返回用户的聊天会话列表。

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"

（可选）使用 <startTime> 指定要获取聊天消息的最早时间点。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

在聊天会话中发送消息

使用 message send 命令将消息发送到刚刚创建的由 threadId 标识的聊天会话。

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"

将 <chatThreadId> 替换为聊天会话 ID。
使用 <content> 提供聊天消息内容。
使用 <messageType> 指定消息内容类型。可能的值为 text 和 html。如果未指定值，则默认值为 text。
（可选）使用 <displayName> 指定发送方的显示名称。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

列出聊天会话中的聊天消息

message list 命令返回聊天会话中的聊天消息列表。

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"

将 <chatThreadId> 替换为聊天会话 ID。
（可选）使用 <startTime> 指定要获取聊天消息的最早时间点。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

从聊天会话接收聊天消息

可以使用 message list 命令检索聊天消息。

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"

将 <chatThreadId> 替换为聊天会话 ID。
将 <messageId> 替换为要检索的消息的 ID。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

发送阅读回执

使用 message receipt send 命令代表用户将已读回执事件发布到会话。

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"

将 <chatThreadId> 替换为聊天会话 ID。
替换 <messageId> 以指定当前用户阅读的最新消息的 ID。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

将用户作为参与者添加到聊天会话

创建聊天会话后，可在其中添加和删除用户。通过添加用户，可向他们授予访问权限，使其能够向聊天会话发送消息，以及添加或删除其他参与者。在调用 participant add 命令之前，请确保已获取该用户的新访问令牌和标识。

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"

将 <chatThreadId> 替换为聊天会话 ID。
将 <userId> 替换为你的 userId。
（可选）使用 <displayName> 指定发送方的显示名称。
（可选）使用 <startTime> 指定要获取聊天消息的最早时间点。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

列出聊天会话中的会话参与者

与添加参与者类似，你也可以列出会话中的参与者。

使用 participant list 检索聊天会话的参与者。

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"

将 <chatThreadId> 替换为聊天会话 ID。
（可选）使用 <skip> 跳过响应中的参与者，直到指定位置为止。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

从聊天会话中删除参与者

可以使用 participant remove 命令从聊天会话中删除聊天参与者。

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"

将 <chatThreadId> 替换为聊天会话 ID。
将 <userId> 替换为要从聊天会话中删除的 userId。
将 <endpoint> 替换为你的 Azure 通信服务终结点。
将 <token> 替换为之前通过运行 identity token issue 命令获得的访问令牌。

先决条件

在开始之前，请务必：

创建活动订阅的 Azure 帐户。有关详细信息，请参阅创建免费账户。
安装 Node.js Active LTS 和 Maintenance LTS 版本。
创建 Azure 通信服务资源。有关详细信息，请参阅创建 Azure 通信服务资源。对于本快速入门，需要记下你的资源终结点和连接字符串。
创建三个 Azure 通信服务用户，并向其颁发用户访问令牌。请确保将范围设置为“聊天”，并记下令牌字符串和 user_id 字符串。完整的演示将创建一个具有两个初始参与者的会话，然后将第三个参与者添加到该会话。还可以使用 Azure CLI，并结合你的连接字符串运行以下命令来创建用户和访问令牌。
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
有关详细信息，请参阅使用 Azure CLI 创建和管理访问令牌。

设置

新建 Web 应用程序

首先，打开终端或命令窗口，为应用创建一个新目录，并导航到该目录。

mkdir chat-quickstart && cd chat-quickstart

运行 npm init -y 以使用默认设置创建 package.json 文件。

npm init -y

安装包

使用 npm install 命令安装适用于 JavaScript 的以下通信服务 SDK。

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

--save 选项将该库作为 package.json 文件中的依赖项列出。

设置应用框架

本快速入门使用 Parcel 捆绑应用程序资产。运行以下命令以安装它，并将其列出为 package.json 中的开发依赖项：

npm install parcel --save-dev

在项目的根目录中创建一个 index.html 文件。我们将使用此文件作为模板，使用适用于 JavaScript 的 Azure 通信聊天 SDK 添加聊天功能。

<!DOCTYPE html>
<html>
  <head>
    <title>Communication Client - Chat Sample</title>
  </head>
  <body>
    <h4>Azure Communication Services</h4>
    <h1>Chat Quickstart</h1>
    <script src="./client.js" type="module"></script>
  </body>
</html>

在名为 client.js 的项目的根目录中创建一个文件，以包含此快速入门的应用程序逻辑。

创建聊天客户端

若要在 Web 应用中创建聊天客户端，需使用通信服务终结点和在前提步骤中生成的访问令牌。

用户访问令牌使你可以构建直接对 Azure 通信服务进行身份验证的客户端应用程序。本快速入门不介绍如何创建服务层来管理聊天应用程序的令牌。有关聊天体系结构的详细信息，请参阅聊天概念，有关访问令牌的详细信息，请参阅用户访问令牌。

在 client.js 内，使用下面代码中的终结点和访问令牌，以及适用于 JavaScript 的 Azure 通信聊天 SDK 添加聊天功能。


import { ChatClient } from '@azure/communication-chat';
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

// Your unique Azure Communication service endpoint
let endpointUrl = '<replace with your resource endpoint>';
// The user access token generated as part of the pre-requisites
let userAccessToken = '<USER_ACCESS_TOKEN>';

let chatClient = new ChatClient(endpointUrl, new AzureCommunicationTokenCredential(userAccessToken));
console.log('Azure Communication Chat client created!');

将 endpointUrl 替换为通信服务资源终结点，如果尚未执行此操作，请参阅创建 Azure 通信服务资源。
将 userAccessToken 替换为你颁发的令牌。

运行代码

运行以下命令以运行你的应用程序：

npx parcel index.html

打开浏览器并导航到 http://localhost:1234/. 在浏览器中的“开发人员工具”控制台中，应会显示以下内容：

Azure Communication Chat client created!

对象模型

以下类和接口用于处理适用于 JavaScript 的 Azure 通信服务聊天 SDK 的某些主要功能。

名称	说明
ChatClient	聊天功能需要此类。你使用订阅信息来实例化此类，使用此类来创建、获取和删除会话，并且订阅到聊天事件。
ChatThreadClient	聊天会话功能需要此类。通过 ChatClient 获取实例，并使用它来发送/接收/更新/删除消息、添加/删除/获取用户、发送键入通知和阅读回执。

启动聊天会话

使用 createThread 方法创建聊天会话。

createThreadRequest 用于描述会话请求：

使用 topic 为此聊天指定主题。在创建聊天会话后可使用 UpdateThread 函数更新主题。
使用 participants 列出要添加到聊天会话的参与者。

解析时，createChatThread 方法返回 CreateChatThreadResult。此模型包含 chatThread 属性，可在其中访问新创建会话的 id。然后可使用 id 获取 ChatThreadClient 的实例。接下来可使用 ChatThreadClient 在会话中执行操作，如发送消息或列出参与者。

async function createChatThread() {
  const createChatThreadRequest = {
    topic: "Hello, World!"
  };
  const createChatThreadOptions = {
    participants: [
      {
        id: { communicationUserId: '<USER_ID>' },
        displayName: '<USER_DISPLAY_NAME>'
      }
    ]
  };
  const createChatThreadResult = await chatClient.createChatThread(
    createChatThreadRequest,
    createChatThreadOptions
  );
  const threadId = createChatThreadResult.chatThread.id;
  return threadId;
}

createChatThread().then(async threadId => {
  console.log(`Thread created:${threadId}`);
  // PLACEHOLDERS
  // <CREATE CHAT THREAD CLIENT>
  // <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD>
  // <SEND MESSAGE TO A CHAT THREAD>
  // <LIST MESSAGES IN A CHAT THREAD>
  // <ADD NEW PARTICIPANT TO THREAD>
  // <LIST PARTICIPANTS IN A THREAD>
  // <REMOVE PARTICIPANT FROM THREAD>
  });

刷新浏览器选项卡时，控制台中应会显示以下内容：

Thread created: <thread_id>

获取聊天会话客户端

getChatThreadClient 方法返回已存在的会话的 chatThreadClient。可使用该方法在创建的会话上执行操作：添加参与者、发送消息等，threadId 是现有聊天会话的唯一 ID。

let chatThreadClient = chatClient.getChatThreadClient(threadId);
console.log(`Chat Thread client for threadId:${threadId}`);

添加此代码以代替 client.js 中的 <CREATE CHAT THREAD CLIENT> 注释，刷新浏览器选项卡并检查控制台，你应该会看到：

Chat Thread client for threadId: <threadId>

列出所有聊天会话

listChatThreads 方法将返回 ChatThreadItem 类型的 PagedAsyncIterableIterator 对象。它可用于列出所有聊天会话。 [ChatThreadItem] 的迭代器是列出线程后返回的响应

const threads = chatClient.listChatThreads();
for await (const thread of threads) {
   // your code here
}

向聊天会话发送消息

使用 sendMessage 方法将消息发送到由 threadId 标识的会话。

sendMessageRequest 用于描述消息请求：

使用 content 提供聊天消息内容；

sendMessageOptions 用于描述操作可选参数：

使用 senderDisplayName 指定发送方的显示名称；
使用 type 指定消息类型，例如 'text' 或 'html'；
可以选择使用 metadata 来包含想随消息一起发送的任何其他数据。此字段为开发人员提供了一种机制，可用于扩展聊天消息功能并为用例添加自定义信息。例如，在消息中共享文件链接时，你可能希望在元数据中添加“hasAttachment: true”，以便收件人的应用程序可分析并相应显示。

SendChatMessageResult 是发送消息后返回的响应，它包含一个 ID（是消息的唯一 ID）。

const sendMessageRequest =
{
  content: 'Please take a look at the attachment'
};
let sendMessageOptions =
{
  senderDisplayName : 'Jack',
  type: 'text',
  metadata: {
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
  }
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;
console.log(`Message sent!, message id:${messageId}`);

添加此代码以代替 client.js 中的 <SEND MESSAGE TO A CHAT THREAD> 注释，刷新浏览器选项卡并检查控制台。

Message sent!, message id:<number>

从聊天会话接收聊天消息

使用实时信令，你可以订阅以侦听新的传入消息并相应更新内存中的当前消息。 Azure 通信服务支持你可以订阅的事件列表。

// open notifications channel
await chatClient.startRealtimeNotifications();
// subscribe to new notification
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // your code here
});

添加此代码以代替 client.js 中的 <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> 注释。刷新浏览器选项卡，控制台中应会显示消息 Notification chatMessageReceived；

或者可以通过按指定间隔轮询 listMessages 方法来检索聊天消息。


const messages = chatThreadClient.listMessages();
for await (const message of messages) {
   // your code here
}

添加此代码以代替 client.js 中的 <LIST MESSAGES IN A CHAT THREAD> 注释。刷新选项卡，应该可以在控制台中找到在这个聊天会话中发送的消息列表。

listMessages 返回可使用 chatMessage.type 标识的不同类型的消息。

有关详细信息，请参阅消息类型。

将用户作为参与者添加到聊天会话

创建聊天会话后，可以在其中添加和删除用户。通过添加用户，可以向他们授予访问权限，使其能够在聊天会话中发送消息，以及添加/删除其他参与者。

在调用 addParticipants 方法之前，请确保已获取该用户的新访问令牌和标识。用户需要使用该访问令牌才能初始化其聊天客户端。

addParticipantsRequest 描述请求对象，其中 participants 列出要添加到聊天会话的参与者；

id（必需）是要添加到聊天会话的通信标识符。
displayName（可选）是会话参与者的显示名称。
shareHistoryTime（可选）是开始与参与者共享聊天历史记录的时间。若要在聊天会话开始后共享历史记录，请将此属性设置为等于或小于会话创建时间的任何日期。若在添加参与者之前不共享任何历史记录，请将其设置为当前日期。若要共享部分历史记录，请将其设置为所选日期。


const addParticipantsRequest =
{
  participants: [
    {
      id: { communicationUserId: '<NEW_PARTICIPANT_USER_ID>' },
      displayName: 'Jane'
    }
  ]
};

await chatThreadClient.addParticipants(addParticipantsRequest);

将 NEW_PARTICIPANT_USER_ID 替换为新用户 ID。在 client.js 中添加此代码以代替 <ADD NEW PARTICIPANT TO THREAD> 注释

列出聊天会话中的用户

const participants = chatThreadClient.listParticipants();
for await (const participant of participants) {
   // your code here
}

添加此代码以代替 client.js 中的 <LIST PARTICIPANTS IN A THREAD> 注释，刷新浏览器选项卡并检查控制台，你应该会看到会话中用户的信息。

从聊天会话中删除用户

与添加参与者类似，可从聊天会话中删除参与者。若要删除，需要跟踪已添加的参与者的 ID。

使用 removeParticipant 方法，其中 participant 是要从会话中删除的通信用户。


await chatThreadClient.removeParticipant({ communicationUserId: <PARTICIPANT_ID> });
await listParticipants();

将 PARTICIPANT_ID 替换为在上一步中使用的用户 ID (<NEW_PARTICIPANT_USER_ID>)。添加此代码以代替 client.js 中的 <REMOVE PARTICIPANT FROM THREAD> 注释。

订阅事件 realTimeNotificationConnected 和 realTimeNotificationDisconnected 可让你了解到到调用服务器的连接何时处于活动状态。

// subscribe to realTimeNotificationConnected event
chatClient.on('realTimeNotificationConnected', () => {
  console.log("Real time notification is now connected!");
  // your code here
});
// subscribe to realTimeNotificationDisconnected event
chatClient.on('realTimeNotificationDisconnected', () => {
  console.log("Real time notification is now disconnected!");
  // your code here
});

代码示例

在 GitHub 上查找此快速入门的最终代码。

先决条件

在开始之前，请务必：

创建活动订阅的 Azure 帐户。有关详细信息，请参阅创建免费账户。
安装 Python 3.7+。
创建 Azure 通信服务资源。有关详细信息，请参阅快速入门：创建和管理通信服务资源。对于本快速入门，需要记下你的资源终结点和连接字符串。
用户访问令牌。请确保将范围设置为“聊天”，并记下令牌字符串和 user_id 字符串。还可以使用 Azure CLI，并结合你的连接字符串运行以下命令来创建用户和访问令牌。
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
有关详细信息，请参阅使用 Azure CLI 创建和管理访问令牌。

设置

创建新的 Python 应用程序

打开终端或命令窗口，为应用创建一个新目录，并转到该目录。

mkdir chat-quickstart && cd chat-quickstart

使用文本编辑器在项目根目录中创建一个名为 start-chat.py 的文件。为程序添加结构，包括基本的异常处理。在以下部分，将此快速入门的所有源代码添加到此文件。

import os
# Add required SDK components from quickstart here

try:
    print('Azure Communication Services - Chat Quickstart')
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

安装 SDK

使用以下命令安装 SDK：


pip install azure-communication-chat

对象模型

以下类和接口用于处理适用于 Python 的 Azure 通信服务聊天 SDK 的某些主要功能。

名称	说明
`ChatClient`	聊天功能需要此类。使用订阅信息实例化此类，并使用它来创建、获取和删除会话。
`ChatThreadClient`	聊天会话功能需要此类。通过 `ChatClient` 获取实例，并使用它来发送、接收、更新和删除消息。此外，可用它来添加、删除和获取用户，还可发送键入通知和已读回执。

创建聊天客户端

为创建聊天客户端，请使用通信服务终结点和在前提步骤期间生成的访问令牌。

pip install azure-communication-identity

from azure.communication.chat import ChatClient, CommunicationTokenCredential

endpoint = "<replace with your resource endpoint>"
chat_client = ChatClient(endpoint, CommunicationTokenCredential("<Access Token>"))

本快速入门不介绍如何创建服务层来管理聊天应用程序的令牌，尽管我们建议你这样做。有关详细信息，请参阅聊天概念的“聊天体系结构”部分。

启动聊天会话

使用 create_chat_thread 方法创建聊天会话。

使用 topic 指定一个会话主题。使用 update_thread 函数创建聊天会话后，可更新主题。
使用 thread_participants 列出要添加到聊天会话的 ChatParticipant。 ChatParticipant 将 CommunicationUserIdentifier 类型视为 user。

CreateChatThreadResult 是创建会话后返回的结果。可用它来提取所创建的聊天会话的 id。然后，可使用此 id 通过 get_chat_thread_client 方法提取 ChatThreadClient 对象。可使用 ChatThreadClient 对此聊天会话执行其他聊天操作。

topic="test topic"

create_chat_thread_result = chat_client.create_chat_thread(topic)
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

获取聊天会话客户端

get_chat_thread_client 方法返回某个已存在的会话的会话客户端。可用它来对创建的会话执行操作。例如，可添加参与者和发送消息。 thread_id 是现有聊天会话的唯一 ID。

可使用 ChatThreadClient 对此聊天会话执行其他聊天操作。

thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(thread_id)

列出所有聊天会话

list_chat_threads 方法返回 ChatThreadItem 类型的迭代器。

使用 start_time 指定要获取聊天会话的最早时间点。
使用 results_per_page 指定每页返回的聊天会话的最大数量。

[ChatThreadItem] 的迭代器是列出会话后返回的响应。

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=2)

chat_threads = chat_client.list_chat_threads(results_per_page=5, start_time=start_time)
for chat_thread_item_page in chat_threads.by_page():
    for chat_thread_item in chat_thread_item_page:
        print(chat_thread_item)
        print('Chat Thread Id: ', chat_thread_item.id)

向聊天会话发送消息

使用 send_message 方法将消息发送到刚刚创建的由 thread_id 标识的聊天会话。

使用 content 提供聊天消息内容。
使用 chat_message_type 指定消息内容类型。可能的值为 text 和 html。如果未指定值，则默认值为 text。
使用 sender_display_name 指定发送方的显示名称。
可以选择使用 metadata 来包含想随消息一起发送的任何附加数据。此字段为开发人员提供了一种机制，可用于扩展聊天消息功能并为用例添加自定义信息。例如，在消息中共享文件链接时，你可能希望在元数据中添加“hasAttachment:true”，以便收件人的应用程序可进行分析并相应地显示。

SendChatMessageResult 是发送消息后返回的响应。它包含一个 ID，这是消息的唯一 ID。

from azure.communication.chat import ChatMessageType

topic = "test topic"
create_chat_thread_result = chat_client.create_chat_thread(topic)
thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)


content='Please take a look at the attachment'
sender_display_name='sender name'
metadata={
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
}

# specify chat message type with pre-built enumerations
send_message_result_w_enum = chat_thread_client.send_message(content=content, sender_display_name=sender_display_name, chat_message_type=ChatMessageType.TEXT, metadata=metadata)
print("Message sent: id: ", send_message_result_w_enum.id)

从聊天会话接收聊天消息

可以通过按指定间隔轮询的 list_messages 方法来检索聊天消息。

使用 results_per_page 指定每页返回的消息的最大数量。
使用 start_time 指定要获取消息的最早时间点。

[ChatMessage] 的迭代器是列出消息后返回的响应。

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=1)

chat_messages = chat_thread_client.list_messages(results_per_page=1, start_time=start_time)
for chat_message_page in chat_messages.by_page():
    for chat_message in chat_message_page:
        print("ChatMessage: Id=", chat_message.id, "; Content=", chat_message.content.message)

list_messages 返回最新版本的消息，包括使用 update_message 和 delete_message 对消息执行的任何编辑或删除。对于已删除的消息，ChatMessage.deleted_on 返回一个 datetime 值，它指示删除该消息的时间。对于已编辑的消息，ChatMessage.edited_on 返回一个 datetime 值，它指示编辑该消息的时间。可使用 ChatMessage.created_on 访问消息创建的原始时间，还可用它来对消息进行排序。

list_messages 返回可使用 ChatMessage.type 标识的不同类型的消息。

有关详细信息，请查看消息类型。

发送阅读回执

使用 send_read_receipt 方法可代表用户将已读回执事件发布到会话。

使用 message_id 指定当前用户阅读的最新消息的 ID。

content='hello world'

send_message_result = chat_thread_client.send_message(content)
chat_thread_client.send_read_receipt(message_id=send_message_result.id)

将用户作为参与者添加到聊天会话

创建聊天会话后，可在其中添加和删除用户。通过添加用户，可向他们授予访问权限，使其能够向聊天会话发送消息，以及添加或删除其他参与者。在调用 add_participants 方法之前，请确保已获取该用户的新访问令牌和标识。用户需要访问令牌才能初始化聊天客户端。

可使用 add_participants 方法将一或多名用户添加到聊天会话，前提是新的访问令牌和标识可用于所有用户。

将返回 list(tuple(ChatParticipant, CommunicationError))。如果已成功添加参与者，则预期会提供一个空列表。如果在添加参与者时遇到错误，则会在该列表中填充未能添加的参与者以及遇到的错误。

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

# create 2 users
identity_client = CommunicationIdentityClient.from_connection_string('<connection_string>')
new_users = [identity_client.create_user() for i in range(2)]

# # conversely, you can also add an existing user to a chat thread; provided the user_id is known
# from azure.communication.identity import CommunicationUserIdentifier
#
# user_id = 'some user id'
# user_display_name = "Wilma Flinstone"
# new_user = CommunicationUserIdentifier(user_id)
# participant = ChatParticipant(
#     identifier=new_user,
#     display_name=user_display_name,
#     share_history_time=datetime.utcnow())

participants = []
for _user in new_users:
  chat_thread_participant = ChatParticipant(
    identifier=_user,
    display_name='Fred Flinstone',
    share_history_time=datetime.utcnow()
  ) 
  participants.append(chat_thread_participant) 

response = chat_thread_client.add_participants(participants)

def decide_to_retry(error, **kwargs):
    """
    Insert some custom logic to decide if retry is applicable based on error
    """
    return True

# verify if all users has been successfully added or not
# in case of partial failures, you can retry to add all the failed participants 
retry = [p for p, e in response if decide_to_retry(e)]
if retry:
    chat_thread_client.add_participants(retry)

列出聊天会话中的会话参与者

与添加参与者类似，你也可以列出会话中的参与者。

使用 list_participants 检索聊天会话的参与者。下面两个命令都是可选的：

results_per_page 用于指定每页返回的参与者人数上限。
skip 用于跳过响应中的参与者，直到指定位置为止。

[ChatParticipant] 的迭代器是列出参与者后返回的响应。

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)

运行代码

从应用程序目录使用 python 命令运行应用程序。

python start-chat.py

代码示例

在 GitHub 上查找此快速入门的最终代码。

先决条件

具有活动订阅的 Azure 帐户。免费创建帐户。
Java 开发工具包 (JDK) 8 或更高版本。
Apache Maven。
创建 Azure 通信服务资源。有关详细信息，请参阅创建 Azure 通信服务资源。对于本快速入门，需要记下你的资源终结点和连接字符串。
用户访问令牌。请确保将范围设置为“聊天”，并记下令牌字符串和 user_id 字符串。还可以使用 Azure CLI，并结合你的连接字符串运行以下命令来创建用户和访问令牌。
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
有关详细信息，请参阅使用 Azure CLI 创建和管理访问令牌。

设置

创建新的 Java 应用程序

打开终端或命令窗口，并导航到要在其中创建 Java 应用程序的目录。运行以下命令以从 maven-archetype-quickstart 模板生成 Java 项目。

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

你会注意到，“生成”目标创建了与 artifactId 名称相同的目录。在此目录下，src/main/java directory 包含项目源代码，src/test/java 目录包含测试源，pom.xml 文件是项目的项目对象模型 (POM)。

将应用程序的 POM 文件更新为使用 Java 8 或更高版本：

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

添加聊天 SDK 的包引用

在 POM 文件中，使用聊天 API 引用 azure-communication-chat 包：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-chat for the latest version --></version>
</dependency>

若要进行身份验证，客户端需引用 azure-communication-common 包：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-common for the latest version --></version>
</dependency>

对象模型

以下类和接口用于处理适用于 Java 的 Azure 通信服务聊天 SDK 的某些主要功能。

名称	说明
ChatClient	聊天功能需要此类。使用订阅信息实例化此类，并使用它来创建、获取和删除会话。
ChatAsyncClient	异步聊天功能需要此类。使用订阅信息实例化此类，并使用它来创建、获取和删除会话。
ChatThreadClient	聊天会话功能需要此类。通过 ChatClient 获取实例，并使用它来发送/接收/更新/删除消息、添加/删除/获取用户、发送键入通知和阅读回执。
ChatThreadAsyncClient	异步聊天会话功能需要此类。通过 ChatAsyncClient 获取实例，并使用它来发送/接收/更新/删除消息、添加/删除/获取用户、发送键入通知和阅读回执。

创建聊天客户端

若要创建聊天客户端，需使用通信服务终结点以及在前提步骤中生成的访问令牌。使用用户访问令牌可以生成直接对 Azure 通信服务进行身份验证的客户端应用程序。在服务器上生成这些令牌后，将它们传回客户端设备。你需要使用 Common SDK 中的 CommunicationTokenCredential 类将令牌传递到聊天客户端。

详细了解聊天体系结构

添加导入语句时，请确保仅从 com.azure.communication.chat 和 com.azure.communication.chat.models 命名空间中添加，而不要从 com.azure.communication.chat.implementation 命名空间中添加。在通过 Maven 生成的 App.java 文件中，可以使用以下代码开始操作：

package com.communication.quickstart;

import com.azure.communication.chat.*;
import com.azure.communication.chat.models.*;
import com.azure.communication.common.*;
import com.azure.core.http.rest.PagedIterable;

import java.io.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Chat Quickstart");

        // Your unique Azure Communication service endpoint
        String endpoint = "<replace with your resource endpoint>";

        // User access token fetched from your trusted service
        String userAccessToken = "<USER_ACCESS_TOKEN>";

        // Create a CommunicationTokenCredential with the given access token, which is only valid until the token is valid
        CommunicationTokenCredential userCredential = new CommunicationTokenCredential(userAccessToken);

        // Initialize the chat client
        final ChatClientBuilder builder = new ChatClientBuilder();
        builder.endpoint(endpoint)
            .credential(userCredential);
        ChatClient chatClient = builder.buildClient();
    }
}

启动聊天会话

使用 createChatThread 方法创建聊天会话。 createChatThreadOptions 用于描述会话请求。

使用构造函数的 topic 参数提供此聊天主题；在使用 UpdateThread 函数创建聊天会话后主题将会更新。
使用 participants 列出要添加到会话的会话参与者。 ChatParticipant 使用你在用户访问令牌快速入门中创建的用户。

CreateChatThreadResult 是从创建聊天线程返回的响应。它包含一个返回 ChatThread 对象的 getChatThread() 方法，该对象可从你获取 ChatThreadClient 的位置得到会话客户端以便对创建的会话执行相关操作：添加参与者、发送消息等。ChatThread 对象还包含用于检索会话唯一 ID 的 getId() 方法。

CommunicationUserIdentifier identity1 = new CommunicationUserIdentifier("<USER_1_ID>");
CommunicationUserIdentifier identity2 = new CommunicationUserIdentifier("<USER_2_ID>");

ChatParticipant firstThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity2)
    .setDisplayName("Participant Display Name 2");

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .addParticipant(firstThreadParticipant)
    .addParticipant(secondThreadParticipant);

CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);
String chatThreadId = result.getChatThread().getId();

列出聊天会话

使用 listChatThreads 方法检索现有聊天会话的列表。

PagedIterable<ChatThreadItem> chatThreads = chatClient.listChatThreads();

chatThreads.forEach(chatThread -> {
    System.out.printf("ChatThread id is %s.\n", chatThread.getId());
});

获取聊天会话客户端

getChatThreadClient 方法返回某个已存在的会话的会话客户端。可使用该方法对创建的会话执行操作：添加参与者、发送消息等。chatThreadId 是现有聊天会话的唯一 ID。

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

在聊天会话中发送消息

使用 sendMessage 方法将消息发送到你创建的由 chatThreadId 标识的会话。 sendChatMessageOptions 用于描述聊天消息请求。

使用 content 提供聊天消息内容。
使用 type 指定聊天消息内容类型（文本或 HTML）。
使用 senderDisplayName 指定发送方的显示名称。
可以选择使用 metadata 来包含想随消息一起发送的任何附加数据。此字段为开发人员提供了一种机制，可用于扩展聊天消息功能并为用例添加自定义信息。例如，在消息中共享文件链接时，你可能希望在元数据中添加 hasAttachment:true，以便接收方的应用程序可分析并相应显示。

响应 sendChatMessageResult 包含 id（消息的唯一 ID）。

Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Please take a look at the attachment")
    .setType(ChatMessageType.TEXT)
    .setSenderDisplayName("Sender Display Name")
    .setMetadata(metadata);

SendChatMessageResult sendChatMessageResult = chatThreadClient.sendMessage(sendChatMessageOptions);
String chatMessageId = sendChatMessageResult.getId();

从聊天会话接收聊天消息

可以通过按指定间隔在聊天会话客户端上轮询 listMessages 方法来检索聊天消息。

chatThreadClient.listMessages().forEach(message -> {
    System.out.printf("Message id is %s.\n", message.getId());
});

listMessages 返回最新版本的消息，包括使用 .editMessage() 和 .deleteMessage() 对消息执行的任何编辑或删除。对于已删除的消息，chatMessage.getDeletedOn() 返回日期/时间值，该值指示该消息删除的时间。对于已编辑的消息，chatMessage.getEditedOn() 返回一个日期/时间值，指示编辑该消息的时间。可以使用 chatMessage.getCreatedOn() 访问消息创建的原始时间，还可使用它对消息进行排序。

单击此处了解有关消息类型的详细信息：消息类型。

发送阅读回执

sendReadReceipt 方法可用于代表用户将阅读回执事件发布到会话。 chatMessageId 是已读聊天消息的唯一 ID。

String chatMessageId = message.getId();
chatThreadClient.sendReadReceipt(chatMessageId);

列出聊天参与者

使用 listParticipants 检索包含由 chatThreadId 标识的聊天线程参与者的分页集合。

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.forEach(chatParticipant -> {
    System.out.printf("Participant id is %s.\n", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId());
});

将用户作为参与者添加到聊天会话

创建聊天会话后，可以在其中添加和删除用户。通过添加用户，可以向他们授予访问权限，使其能够在聊天会话中发送消息，以及添加/删除其他参与者。首先需要获取该用户的新访问令牌和标识。在调用 addParticipants 方法之前，请确保已获取该用户的新访问令牌和标识。用户需要使用该访问令牌才能初始化聊天客户端。

使用 addParticipants 方法将参与者添加到该会话中。

communicationIdentifier，必需，是你已在用户访问令牌快速入门中通过 CommunicationIdentityClient 创建的 CommunicationIdentifier。
displayName（可选）是会话参与者的显示名称。
shareHistoryTime（可选）是开始与参与者共享聊天历史记录的时间。若要在聊天会话开始后共享历史记录，请将此属性设置为等于或小于会话创建时间的任何日期。若在添加参与者之前不共享任何历史记录，请将其设置为当前日期。若要共享部分历史记录，请将其设置为所需日期。

List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

CommunicationUserIdentifier identity3 = new CommunicationUserIdentifier("<USER_3_ID>");
CommunicationUserIdentifier identity4 = new CommunicationUserIdentifier("<USER_4_ID>");

ChatParticipant thirdThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity3)
    .setDisplayName("Display Name 3");

ChatParticipant fourthThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity4)
    .setDisplayName("Display Name 4");

participants.add(thirdThreadParticipant);
participants.add(fourthThreadParticipant);

chatThreadClient.addParticipants(participants);

运行代码

导航到包含 pom.xml 文件的目录，并使用以下 mvn 命令编译该项目。

mvn compile

然后，生成包。

mvn package

运行以下 mvn 命令以执行应用。

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

代码示例

在 GitHub 上查找此快速入门的最终代码。

先决条件

在开始之前，请务必：

创建活动订阅的 Azure 帐户。有关详细信息，请参阅创建免费账户。
安装 Android Studio，我们将使用 Android Studio 为快速入门创建一个 Android 应用程序以安装依赖项。
创建 Azure 通信服务资源。有关详细信息，请参阅创建 Azure 通信服务资源。对于本快速入门，需要记下你的资源终结点和连接字符串。
创建两个通信服务用户，并向他们颁发用户访问令牌。请确保将范围设置为“聊天”，并记下令牌字符串和 user_id 字符串。在本快速入门中，我们将创建一个包含初始参与者的会话，然后将第二个参与者添加到该会话中。还可以使用 Azure CLI，并结合你的连接字符串运行以下命令来创建用户和访问令牌。
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
有关详细信息，请参阅使用 Azure CLI 创建和管理访问令牌。

设置

创建新的 Android 应用程序

打开 Android Studio，然后选择 Create a new project。
在下一个窗口中，选择 Empty Activity 作为项目模板。
在选择选项时，输入 ChatQuickstart 作为项目名称。
单击“下一步”，然后选择要在其中创建项目的目录。

安装库

我们将使用 Gradle 来安装所需的通信服务依赖项。在命令行中，导航到 ChatQuickstart 项目的根目录。打开应用的 build.gradle 文件，并将以下依赖项添加到 ChatQuickstart 目标中：

implementation 'com.azure.android:azure-communication-common:' + $azureCommunicationCommonVersion
implementation 'com.azure.android:azure-communication-chat:' + $azureCommunicationChatVersion
implementation 'org.slf4j:slf4j-log4j12:1.7.29'

在 root build.gradle 的打包选项中排除元文件

android {
   ...
    packagingOptions {
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/license'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/notice'
        exclude 'META-INF/ASL2.0'
        exclude("META-INF/*.md")
        exclude("META-INF/*.txt")
        exclude("META-INF/*.kotlin_module")
    }
}

（替代方案）通过 Maven 安装库

若要使用 Maven 生成系统将库导入项目，请将其添加到应用的 pom.xml 文件的 dependencies 部分，同时指定你要使用的项目 ID 和版本：

<dependency>
  <groupId>com.azure.android</groupId>
  <artifactId>azure-communication-chat</artifactId>
  <version><!-- Please refer to https://search.maven.org/artifact/com.azure.android/azure-communication-chat for the latest version --></version>
</dependency>

设置 Azure 函数

有关详细信息，请查看 Azure 函数集成。强烈建议与 Azure 函数集成，以免对应用程序参数进行硬编码。

设置应用程序常量：

创建存储所有应用程序常量的类 ApplicationConstants：

public class ApplicationConstants {
    public static final String SDK_VERSION = "<your_version>";
    public final static String SDK_NAME = "azure-communication-com.azure.android.communication.chat";
    public final static String APPLICATION_ID = "Chat_Test_App";
    public final static String TAG = "[Chat Test App]";
    public static CommunicationTokenCredential COMMUNICATION_TOKEN_CREDENTIAL;
}

设置占位符

打开并编辑文件 MainActivity.java。在本快速入门中，我们要将代码添加到 MainActivity，并在控制台中查看输出。本快速入门不涉及生成 UI。在文件顶部，导入 Azure Communication Common、Azure Communication Chat 和其他系统库：

import com.azure.android.communication.chat.*;
import com.azure.android.communication.chat.models.*;
import com.azure.android.communication.common.*;

import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;

import com.jakewharton.threetenabp.AndroidThreeTen;

import java.util.ArrayList;
import java.util.List;

将以下代码复制到文件 MainActivity.java 中的类 MainActivity 中：

    private ChatAsyncClient chatAsyncClient;

    private void log(String msg) {
        Log.i(TAG, msg);
        Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
    }
    
   @Override
    protected void onStart() {
        super.onStart();
        try {
            AndroidThreeTen.init(this);

            // Initialize application parameters if one of the conditions in '### Initialize Application Parameters' are met.

            // <CREATE A CHAT CLIENT>

            // <CREATE A CHAT THREAD>

            // <CREATE A CHAT THREAD CLIENT>

            // <SEND A MESSAGE>
            
            // <RECEIVE CHAT MESSAGES>

            // <ADD A USER>

            // <LIST USERS>

            // <REMOVE A USER>
            
            // <<SEND A TYPING NOTIFICATION>>
            
            // <<SEND A READ RECEIPT>>
               
            // <<LIST READ RECEIPTS>>
        } catch (Exception e){
            System.out.println("Quickstart failed: " + e.getMessage());
        }
    }

初始化应用程序参数

注意

如果满足以下任一条件，则需要将正在初始化的 ApplicationConstants 添加到 MainActivity.java：1. 未启用推送通知功能。 2. 适用于 Android 的 Azure 通信聊天库的版本 <“2.0.0”。否则，请参阅 Android 推送通知中的步骤 11。请参阅用作参考的 SDK 版本的示例应用。

ACS_ENDPOINT、FIRST_USER_ID 和 FIRST_USER_ACCESS_TOKEN 是在调用 Azure 函数后返回的。有关详细信息，请查看 Azure 函数集成。我们使用调用 Azure 函数后的响应来初始化参数列表：

ACS_ENDPOINT：通信服务资源的终结点。
FIRST_USER_ID 和 SECOND_USER_ID：通信服务资源生成的有效通信服务用户 ID。
FIRST_USER_ACCESS_TOKEN：<FIRST_USER_ID> 的通信服务访问令牌。

代码块，通过调用 Azure 函数来初始化应用程序参数：

try {
        UserTokenClient userTokenClient = new UserTokenClient(AZURE_FUNCTION_URL);
        //First user context
        userTokenClient.getNewUserContext();
        ACS_ENDPOINT = userTokenClient.getACSEndpoint();
        FIRST_USER_ID = userTokenClient.getUserId();
        FIRST_USER_ACCESS_TOKEN = userTokenClient.getUserToken();
        COMMUNICATION_TOKEN_CREDENTIAL = new CommunicationTokenCredential(FIRST_USER_ACCESS_TOKEN);
        //Second user context
        userTokenClient.getNewUserContext();
        SECOND_USER_ID = userTokenClient.getUserId();
    } catch (Throwable throwable) {
        //Your handling code
        logger.logThrowableAsError(throwable);
    }

创建聊天客户端

将注释 <CREATE A CHAT CLIENT> 替换为以下代码（将 import 语句放在文件顶部）：

import com.azure.android.core.http.policy.UserAgentPolicy;

chatAsyncClient = new ChatClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .buildAsyncClient();

对象模型

以下类和接口用于处理适用于 JavaScript 的 Azure 通信服务聊天 SDK 的某些主要功能。

名称	说明
ChatClient/ChatAsyncClient	聊天功能需要此类。你使用订阅信息来实例化此类，使用此类来创建、获取和删除会话，以及订阅聊天事件。
ChatThreadClient/ChatThreadAsyncClient	聊天会话功能需要此类。通过 ChatClient 获取实例，并使用它来发送/接收/更新/删除消息、添加/删除/获取用户、发送键入通知和阅读回执。

启动聊天会话

我们将使用自己的 ChatAsyncClient 来创建包含一个初始用户的新会话。

使用下面的代码替换 <CREATE A CHAT THREAD> 注释：

// A list of ChatParticipant to start the thread with.
List<ChatParticipant> participants = new ArrayList<>();
// The display name for the thread participant.
String displayName = "initial participant";
participants.add(new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(firstUserId))
    .setDisplayName(displayName));

// The topic for the thread.
final String topic = "General";
// Optional, set a repeat request ID.
final String repeatabilityRequestID = "";
// Options to pass to the create method.
CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions()
    .setTopic(topic)
    .setParticipants(participants)
    .setIdempotencyToken(repeatabilityRequestID);

CreateChatThreadResult createChatThreadResult =
    chatAsyncClient.createChatThread(createChatThreadOptions).get();
ChatThreadProperties chatThreadProperties = createChatThreadResult.getChatThreadProperties();
threadId = chatThreadProperties.getId();

获取聊天会话客户端

现在我们已经创建了聊天会话，接下来将获得一个 ChatThreadAsyncClient，用于在会话内执行操作。使用下面的代码替换 <CREATE A CHAT THREAD CLIENT> 注释：

ChatThreadAsyncClient chatThreadAsyncClient = new ChatThreadClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .chatThreadId(threadId)
    .buildAsyncClient();

向聊天会话发送消息

现在将消息发送到该会话。

使用下面的代码替换 <SEND A MESSAGE> 注释：

// The chat message content, required.
final String content = "Please take a look at the attachment";

// The display name of the sender, if null (i.e. not specified), an empty name will be set.
final String senderDisplayName = "An important person";

// Use metadata optionally to include any additional data you want to send along with the message.
// This field provides a mechanism for developers to extend chat message functionality and add
// custom information for your use case. For example, when sharing a file link in the message, you
// might want to add 'hasAttachment:true' in metadata so that recipient's application can parse
// that and display accordingly.
final Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions chatMessageOptions = new SendChatMessageOptions()
    .setType(ChatMessageType.TEXT)
    .setContent(content)
    .setSenderDisplayName(senderDisplayName)
    .setMetadata(metadata);

// A string is the response returned from sending a message, it is an id, which is the unique ID
// of the message.
chatMessageId = chatThreadAsyncClient.sendMessage(chatMessageOptions).get().getId();

从聊天会话接收聊天消息

实时通知

使用实时信令，可以订阅新的传入消息并相应更新内存中的当前消息。 Azure 通信服务支持你可以订阅的事件列表。

将注释 <RECEIVE CHAT MESSAGES> 替换为以下代码（将 import 语句放在文件顶部）：


// Start real time notification
chatAsyncClient.startRealtimeNotifications(firstUserAccessToken, getApplicationContext());

// Register a listener for chatMessageReceived event
chatAsyncClient.addEventHandler(ChatEventType.CHAT_MESSAGE_RECEIVED, (ChatEvent payload) -> {
    ChatMessageReceivedEvent chatMessageReceivedEvent = (ChatMessageReceivedEvent) payload;
    // You code to handle chatMessageReceived event
    
});

重要

已知问题：在同一应用程序中同时使用 Android 聊天和调用 SDK 时，聊天 SDK 的实时通知功能不起作用。可能会遇到依赖项解析问题。虽然正在研究解决方案，但可通过在应用的 build.gradle 文件中添加以下依赖项信息来关闭实时通知功能，并轮询 GetMessages API 以向用户显示传入消息。

implementation ("com.azure.android:azure-communication-chat:1.0.0") {
    exclude group: 'com.microsoft', module: 'trouter-client-android'
}
implementation 'com.azure.android:azure-communication-calling:1.0.0'

对于上面的更新，请注意，如果应用程序尝试触摸任何通知 API（如 chatAsyncClient.startRealtimeNotifications() 或 chatAsyncClient.addEventHandler()），则会出现运行时错误。

推送通知

有关详细信息，请参阅 Android 推送通知。

将用户作为参与者添加到聊天会话

使用下面的代码替换 <ADD A USER> 注释：

// The display name for the thread participant.
String secondUserDisplayName = "a new participant";
ChatParticipant participant = new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(secondUserId))
    .setDisplayName(secondUserDisplayName);
        
chatThreadAsyncClient.addParticipant(participant);

列出会话中的用户

将注释 <LIST USERS> 替换为以下代码（将 import 语句放在文件顶部）：

import com.azure.android.core.rest.util.paging.PagedAsyncStream;
import com.azure.android.core.util.RequestContext;

// The maximum number of participants to be returned per page, optional.
int maxPageSize = 10;

// Skips participants up to a specified position in response.
int skip = 0;

// Options to pass to the list method.
ListParticipantsOptions listParticipantsOptions = new ListParticipantsOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatParticipant> participantsPagedAsyncStream =
      chatThreadAsyncClient.listParticipants(listParticipantsOptions, RequestContext.NONE);

participantsPagedAsyncStream.forEach(chatParticipant -> {
    // You code to handle participant
});

从聊天会话中删除用户

现在从该会话中删除第二个用户。

使用下面的代码替换 <REMOVE A USER> 注释：

// Using the unique ID of the participant.
chatThreadAsyncClient.removeParticipant(new CommunicationUserIdentifier(secondUserId)).get();

发送键入通知

使用下面的代码替换 <SEND A TYPING NOTIFICATION> 注释：

chatThreadAsyncClient.sendTypingNotification().get();

发送阅读回执

将为上面发送的消息发送阅读回执。

使用下面的代码替换 <SEND A READ RECEIPT> 注释：

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

列出阅读回执

使用下面的代码替换 <READ RECEIPTS> 注释：

// The maximum number of participants to be returned per page, optional.
maxPageSize = 10;
// Skips participants up to a specified position in response.
skip = 0;
// Options to pass to the list method.
ListReadReceiptOptions listReadReceiptOptions = new ListReadReceiptOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatMessageReadReceipt> readReceiptsPagedAsyncStream =
      chatThreadAsyncClient.listReadReceipts(listReadReceiptOptions, RequestContext.NONE);

readReceiptsPagedAsyncStream.forEach(readReceipt -> {
    // You code to handle readReceipt
});

运行代码

在 Android Studio 中，点击“运行”按钮以生成并运行项目。在控制台中，可以查看代码的输出和 ChatClient 的记录器输出。

代码示例

在 GitHub 上查找此快速入门的最终代码。

先决条件

在开始之前，请务必：

创建活动订阅的 Azure 帐户。有关详细信息，请参阅创建免费账户。
安装 Visual Studio
创建 Azure 通信服务资源。有关详细信息，请参阅创建 Azure 通信服务资源。对于本快速入门，需要记下你的资源终结点和连接字符串。
用户访问令牌。请确保将范围设置为“聊天”，并记下令牌字符串和 user_id 字符串。还可以使用 Azure CLI，并结合你的连接字符串运行以下命令来创建用户和访问令牌。
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
有关详细信息，请参阅使用 Azure CLI 创建和管理访问令牌。

设置

新建 C# 应用程序

在控制台窗口（例如 cmd、PowerShell 或 Bash）中，使用 dotnet new 命令创建名为 ChatQuickstart 的新控制台应用。此命令将创建包含单个源文件的简单“Hello World”C# 项目：Program.cs。

dotnet new console -o ChatQuickstart

将目录更改为新创建的应用文件夹，并使用 dotnet build 命令编译应用程序。

cd ChatQuickstart
dotnet build

安装包

安装适用于 .NET 的 Azure 通信聊天 SDK

dotnet add package Azure.Communication.Chat

对象模型

以下类用于处理适用于 C# 的 Azure 通信服务聊天 SDK 的某些主要功能。

名称	说明
ChatClient	聊天功能需要此类。使用订阅信息实例化此类，并使用它来创建、获取和删除会话。
ChatThreadClient	聊天会话功能需要此类。通过 ChatClient 获取实例，并使用它来发送/接收/更新/删除消息、添加/删除/获取参与者、发送键入通知和阅读回执。

创建聊天客户端

若要创建聊天客户端，你需要使用通信服务终结点以及在先决条件步骤中生成的访问令牌。你需要使用标识 SDK 中的 CommunicationIdentityClient 类来创建用户，并颁发要传递到聊天客户端的令牌。

详细了解用户访问令牌。

本快速入门不介绍如何创建服务层来管理聊天应用程序的令牌，尽管我们建议你这样做。详细了解聊天体系结构

复制以下代码片段，并将其粘贴到源文件 Program.cs 中

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Azure Communication service endpoint
            Uri endpoint = new Uri("<replace with your resource endpoint>");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

启动聊天会话

在 chatClient 上使用 createChatThread 方法创建聊天会话

使用 topic 为该聊天提供一个主题；在创建聊天会话后可使用 UpdateTopic 函数更新主题。
使用 participants 属性传递要添加到聊天会话的 ChatParticipant 对象的列表。使用 CommunicationIdentifier 对象初始化 ChatParticipant 对象。 CommunicationIdentifier 可以是 CommunicationUserIdentifier、MicrosoftTeamsUserIdentifier 或 PhoneNumberIdentifier 类型。例如，若要获取 CommunicationIdentifier 对象，需要传递按照创建用户中的说明创建的访问 ID

createChatThread 方法的 response 对象包含 chatThread 详细信息。若要与聊天会话操作（例如添加参与者、发送消息、删除消息，等等）进行交互，需要在 ChatClient 客户端上使用 GetChatThreadClient 方法将 chatThreadClient 客户端实例实例化。

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<Access_ID>"))
{
    DisplayName = "UserDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

获取聊天会话客户端

GetChatThreadClient 方法返回某个已存在的会话的会话客户端。它可用于在创建的会话上执行操作：添加成员、发送消息等，threadId 是现有聊天会话的唯一 ID。

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

列出所有聊天会话

使用 GetChatThreads 可检索用户所属的所有聊天线程。

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

向聊天会话发送消息

使用 SendMessage 向会话发送消息。

使用 content 提供消息的内容，这是必需的。
使用 type 表示消息的内容类型，例如 'Text' 或 'Html'。如果未指定，则会将其设置为 'Text'。
使用 senderDisplayName 指定发送方的显示名称。如果未指定，则会将其设置为空字符串。
可以选择使用 metadata 来包含想随消息一起发送的任何附加数据。此字段为开发人员提供了一种机制，可用于扩展聊天消息功能并为用例添加自定义信息。例如，在消息中共享文件链接时，你可能希望在元数据中添加“hasAttachment:true”，以便收件人的应用程序可分析并相应显示。

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Please take a look at the attachment",
    MessageType = ChatMessageType.Text
};
sendChatMessageOptions.Metadata["hasAttachment"] = "true";
sendChatMessageOptions.Metadata["attachmentUrl"] = "https://contoso.com/files/attachment.docx";

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

从聊天会话接收聊天消息

可以通过按指定间隔在聊天会话客户端上轮询 GetMessages 方法来检索聊天消息。

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

GetMessages 采用可选的 DateTimeOffset 参数。如果指定了该偏移量，你将收到在其之后接收、更新或删除的消息。请注意，还会返回在偏移时间之前收到但在该时间之后编辑过或删除的消息。

GetMessages 返回最新版本的消息，包括使用 UpdateMessage 和 DeleteMessage 对消息执行的任何编辑或删除。对于已删除的消息，chatMessage.DeletedOn 返回日期/时间值，该值指示该消息删除的时间。对于已编辑的消息，chatMessage.EditedOn 返回一个日期/时间值，指示编辑该消息的时间。可以使用 chatMessage.CreatedOn 访问消息创建的原始时间，还可使用它对消息进行排序。

GetMessages 返回可使用 chatMessage.Type 标识的不同类型的消息。这些类型包括：

Text：会话成员发送的普通聊天消息。
Html：格式化文本消息。请注意，通信服务用户当前无法发送 RichText 消息。在 Teams Interop 方案中，此消息类型支持将消息从 Teams 用户传递到通信服务用户。
TopicUpdated：指示主题已更新的系统消息。（只读）
ParticipantAdded：系统消息，指示一个或多个参与者已添加到聊天会话。（只读）
ParticipantRemoved：指示已从聊天会话中删除参与者的系统消息。

有关详细信息，请参阅消息类型。

将用户作为参与者添加到聊天会话

创建会话后，可以在其中添加和删除用户。通过添加用户，可以向他们授予访问权限，使其能够向会话发送消息，以及添加/删除其他参与者。在调用 AddParticipants 之前，请确保已获取该用户的新访问令牌和标识。用户需要使用该访问令牌才能初始化其聊天客户端。

使用 AddParticipants 将一个或多个参与者添加到聊天会话。下面是对每个会话参与者支持的属性：

communicationUser，必需，是会话参与者的标识。
displayName（可选）是会话参与者的显示名称。
shareHistoryTime，可选，是开始与参与者共享聊天历史记录的时间。

var josh = new CommunicationUserIdentifier(id: "<Access_ID_For_Josh>");
var gloria = new CommunicationUserIdentifier(id: "<Access_ID_For_Gloria>");
var amy = new CommunicationUserIdentifier(id: "<Access_ID_For_Amy>");

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants: participants);

获取会话参与者

使用 GetParticipants 检索聊天会话的参与者。

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

发送阅读回执

使用 SendReadReceipt 通知其他参与者：用户已阅读该消息。

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

运行代码

从应用程序目录使用 dotnet run 命令运行应用程序。

dotnet run

代码示例

在 GitHub 上查找此快速入门的最终代码。

先决条件

在开始之前，请务必：

创建活动订阅的 Azure 帐户。有关详细信息，请参阅创建免费账户。
安装 Xcode 和 CocoaPods。使用 Xcode 创建用于快速入门的 iOS 应用程序，并使用 Cocoapods 来安装依赖项。
创建 Azure 通信服务资源。有关详细信息，请参阅快速入门：创建和管理通信服务资源。对于本快速入门，需要记下你的资源终结点和连接字符串。
在 Azure 通信服务中创建两个用户，并向他们颁发用户访问令牌。请确保将范围设置为“聊天”，并记下令牌字符串和 user_id 字符串。在本快速入门中，创建一个包含初始参与者的会话，然后将第二个参与者添加到该会话中。还可以使用 Azure CLI，并结合你的连接字符串运行以下命令来创建用户和访问令牌。
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
有关详细信息，请参阅使用 Azure CLI 创建和管理访问令牌。

设置

创建新的 iOS 应用程序

打开 Xcode，并选择“新建 Xcode 项目”。然后选择“iOS”作为平台，选择“应用”作为模板。

在项目名称处，输入 ChatQuickstart。然后选择“Storyboard”作为界面，“UIKit App Delegate”作为生命周期，“Swift”作为语言。

选择“下一步”，然后选择要在其中创建项目的目录。

安装库

使用 Cocoapods 来安装所需的通信服务依赖项。

在命令行中，导航到 ChatQuickstart iOS 项目的根目录。通过以下命令创建 Podfile：pod init。

打开 Podfile，并向 ChatQuickstart 目标添加以下依赖项：

pod 'AzureCommunicationChat', '~> 1.3.6'

通过以下命令安装依赖项：pod install。请注意，这还会创建 Xcode 工作区。

运行 pod install 后，通过选择新建的 .xcworkspace以重新在 Xcode 中打开项目。

设置占位符

在 Xcode 中打开工作区 ChatQuickstart.xcworkspace，然后打开 ViewController.swift。

在本快速入门中，将代码添加到 viewController，并在 Xcode 控制台中查看输出。本快速入门不涉及在 iOS 中构建用户界面。

在 viewController.swift 的顶部导入 AzureCommunication 和 AzureCommunicatonChat 库：

import AzureCommunicationCommon
import AzureCommunicationChat

将以下代码复制到 ViewController 的 viewDidLoad() 方法中：

override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.

        let semaphore = DispatchSemaphore(value: 0)
        DispatchQueue.global(qos: .background).async {
            do {
                // <CREATE A CHAT CLIENT>
                
                // <CREATE A CHAT THREAD>

                // <LIST ALL CHAT THREADS>

                // <GET A CHAT THREAD CLIENT>

                // <SEND A MESSAGE>

                // <SEND A READ RECEIPT >

                // <RECEIVE MESSAGES>

                // <ADD A USER>
                
                // <LIST USERS>
            } catch {
                print("Quickstart failed: \(error.localizedDescription)")
            }
        }
    }

为了便于演示，我们将使用信号灯来同步代码。在以下步骤中，使用 Azure 通信服务聊天库将占位符替换为示例代码。

创建聊天客户端

若要创建聊天客户端，你需要使用通信服务终结点以及在先决条件步骤中生成的访问令牌。

详细了解用户访问令牌。

本快速入门不介绍如何创建服务层来管理聊天应用程序的令牌，尽管我们建议你这样做。详细了解聊天体系结构

将注释 <CREATE A CHAT CLIENT> 替换为以下代码片段：

let endpoint = "<ACS_RESOURCE_ENDPOINT>"
let credential =
try CommunicationTokenCredential(
    token: "<ACCESS_TOKEN>"
)
let options = AzureCommunicationChatClientOptions()

let chatClient = try ChatClient(
    endpoint: endpoint,
    credential: credential,
    withOptions: options
)

将 <ACS_RESOURCE_ENDPOINT> 替换为 Azure 通信服务资源的终结点。将 <ACCESS_TOKEN> 替换为有效的通信服务访问令牌。

对象模型

以下类和接口用于处理适用于 iOS 的 Azure 通信服务聊天 SDK 的某些主要功能。

名称	说明
`ChatClient`	聊天功能需要此类。你使用订阅信息来实例化此类，使用此类来创建、获取和删除会话，以及订阅聊天事件。
`ChatThreadClient`	聊天会话功能需要此类。通过 `ChatClient` 获取实例，并使用它来发送、接收、更新和删除消息。还可以使用此类来添加、删除和获取用户，发送“正在键入”通知和已读回执。

启动聊天会话

CreateChatThreadResult 是从创建聊天线程返回的响应。它包含 chatThread 属性（ChatThreadProperties 对象）。此对象包含的 threadId 可用于获取 ChatThreadClient，后者用于对创建的会话执行各种操作：添加参与者、发送消息等。

将注释 <CREATE A CHAT THREAD> 替换为以下代码片段：

let request = CreateChatThreadRequest(
    topic: "Quickstart",
    participants: [
        ChatParticipant(
            id: CommunicationUserIdentifier("<USER_ID>"),
            displayName: "Jack"
        )
    ]
)

var threadId: String?
chatClient.create(thread: request) { result, _ in
    switch result {
    case let .success(result):
        threadId = result.chatThread?.id

    case .failure:
        fatalError("Failed to create thread.")
    }
    semaphore.signal()
}
semaphore.wait()

将 <USER_ID> 替换为有效的通信服务用户 ID。

在此处使用信号灯等待完成事件处理器，然后再继续。在后续步骤中，将使用返回到完成事件处理器的响应中的 threadId。

列出所有聊天会话

创建聊天会话后，可以通过在 ChatClient 上调用 listChatThreads 方法来列出所有聊天会话。使用下面的代码替换 <LIST ALL CHAT THREADS> 注释：

chatClient.listThreads { result, _ in
    switch result {
    case let .success(threads):
        guard let chatThreadItems = threads.pageItems else {
            print("No threads returned.")
            return
        }

        for chatThreadItem in chatThreadItems {
            print("Thread id: \(chatThreadItem.id)")
        }
    case .failure:
        print("Failed to list threads")
    }
    semaphore.signal()
}
semaphore.wait()

获取聊天会话客户端

createClient 方法返回已存在的会话的 ChatThreadClient。可使用该方法在创建的会话上执行操作：添加参与者、发送消息等，threadId 是现有聊天会话的唯一 ID。

使用下面的代码替换 <GET A CHAT THREAD CLIENT> 注释：

let chatThreadClient = try chatClient.createClient(forThread: threadId!)

向聊天会话发送消息

使用 send 方法将消息发送到由 threadId 标识的会话。

SendChatMessageRequest 用于描述消息请求：

使用 content 提供聊天消息内容
使用 senderDisplayName 指定发送方的显示名称
使用 type 指定消息类型，例如 'text' 或 'html'
可以选择使用 metadata 来包含想随消息一起发送的任何附加数据。此字段为开发人员提供了一种机制，可用于扩展聊天消息功能并为用例添加自定义信息。例如，在消息中共享文件链接时，你可能希望在元数据中添加“hasAttachment:true”，以便收件人的应用程序可分析并相应显示。

SendChatMessageResult 是发送消息后返回的响应，它包含一个 ID（是消息的唯一 ID）。

将注释 <SEND A MESSAGE> 替换为以下代码片段：

let message = SendChatMessageRequest(
                        content: "Hello!",
                        senderDisplayName: "Jack",
                        type: .text,
                        metadata: [
                            "hasAttachment": "true",
                            "attachmentUrl": "https://contoso.com/files/attachment.docx"
                        ]
                    )

var messageId: String?

chatThreadClient.send(message: message) { result, _ in
    switch result {
    case let .success(result):
        print("Message sent, message id: \(result.id)")
        messageId = result.id
    case .failure:
        print("Failed to send message")
    }
    semaphore.signal()
}
semaphore.wait()

发送阅读回执

sendReadReceipt 方法可用于代表用户将阅读回执事件发布到会话。 messageId 是已读聊天消息的唯一 ID。

将注释 <SEND A READ RECEIPT> 替换为以下代码：

if let id = messageId {
    chatThreadClient.sendReadReceipt(forMessage: id) { result, _ in
        switch result {
        case .success:
            print("Read receipt sent")
        case .failure:
            print("Failed to send read receipt")
        }
        semaphore.signal()
    }
    semaphore.wait()
} else {
    print("Cannot send read receipt without a message id")
}

从聊天会话接收聊天消息

使用实时信令，你可以订阅以侦听新的传入消息并相应更新内存中的当前消息。 Azure 通信服务支持你可以订阅的事件列表。

将注释 <RECEIVE MESSAGES> 替换为以下代码。启用通知后，请尝试发送新消息以查看 ChatMessageReceivedEvents。

chatClient.startRealTimeNotifications { result in
    switch result {
    case .success:
        print("Real-time notifications started.")
    case .failure:
        print("Failed to start real-time notifications.")
    }
    semaphore.signal()
}
semaphore.wait()

chatClient.register(event: .chatMessageReceived, handler: { response in
    switch response {
    case let .chatMessageReceivedEvent(event):
        print("Received a message: \(event.message)")
    default:
        return
    }
})

或者可以通过按指定间隔轮询 listMessages 方法来检索聊天消息。请查看以下适用于 listMessages 的代码片段

chatThreadClient.listMessages { result, _ in
    switch result {
    case let .success(messagesResult):
        guard let messages = messagesResult.pageItems else {
            print("No messages returned.")
            return
        }

        for message in messages {
            print("Received message with id: \(message.id)")
        }

    case .failure:
        print("Failed to receive messages")
    }
    semaphore.signal()
}
semaphore.wait()

将用户作为参与者添加到聊天会话

创建会话后，可以在其中添加和删除用户。通过添加用户，可以向他们授予访问权限，使其能够向会话发送消息，以及添加/删除其他参与者。在调用 add 之前，请确保已获取该用户的新访问令牌和标识。用户需要使用该访问令牌才能初始化其聊天客户端。

使用 ChatThreadClient 的 add 方法将一个或多个参与者添加到聊天会话。下面是对每个会话参与者支持的属性：

id，必需，是会话参与者的标识。
displayName（可选）是会话参与者的显示名称。
shareHistoryTime，可选，是开始与参与者共享聊天历史记录的时间。

使用下面的代码替换 <ADD A USER> 注释：

let user = ChatParticipant(
    id: CommunicationUserIdentifier("<USER_ID>"),
    displayName: "Jane"
)

chatThreadClient.add(participants: [user]) { result, _ in
    switch result {
    case let .success(result):
        if let errors = result.invalidParticipants, !errors.isEmpty {
            print("Error adding participant")
        } else {
            print("Added participant")
        }
    case .failure:
        print("Failed to add the participant")
    }
    semaphore.signal()
}
semaphore.wait()

将 <USER_ID> 替换为要添加的用户的通信服务用户 ID。

列出会话中的用户

使用 listParticipants 方法可获取特定聊天会话的所有参与者。

使用下面的代码替换 <LIST USERS> 注释：

chatThreadClient.listParticipants { result, _ in
    switch result {
    case let .success(participantsResult):
        guard let participants = participantsResult.pageItems else {
            print("No participants returned.")
            return
        }

        for participant in participants {
            let user = participant.id as! CommunicationUserIdentifier
            print("User with id: \(user.identifier)")
        }
    case .failure:
        print("Failed to list participants")
    }
    semaphore.signal()
}
semaphore.wait()

推送通知

在移动端未在前台运行的情况下，推送通知可以通知客户端聊天线程中的传入消息。目前 IOS SDK 1.3.0 版本支持使用通知中心发送聊天推送通知。有关详细信息，请参阅聊天应用中的“启用推送通知”一文。

运行代码

在 Xcode 中，单击“运行”按钮以生成并运行项目。在控制台中，可以从代码中查看输出，并从 ChatClient 查看记录器输出。

注意：请将 Build Settings > Build Options > Enable Bitcode 设置为 No。目前，适用于 iOS 的 AzureCommunicationChat SDK 不支持启用 Bitcode，以下 GitHub 问题跟踪的就是此问题。

代码示例

在 GitHub 上查找此快速入门的最终代码。

先决条件

具备有效订阅的 Azure 帐户，或免费创建一个 Azure 帐户。
有效的 Azure 通信服务资源，或创建一个通信服务资源。
有效的 Azure 逻辑应用资源或使用您要使用的触发器创建空白逻辑应用。目前，通信服务聊天连接器仅提供操作，因此逻辑应用至少需要一个触发器。

创建用户

在编辑模式下打开 Power Automate 流程，完成 Power Automate 中的这些步骤。

若要使用通信服务标识连接器在工作流中添加新步骤，请执行以下操作：

在设计器中，在要添加新操作的步骤下，选择“新建步骤”。或者，若要在步骤之间添加新操作，请将指针移到这些步骤之间的箭头上方，选择加号 (+)，然后选择“添加操作”。
在“选择操作”搜索框中，输入通信服务标识。在操作列表中，选择“创建用户”。
输入连接字符串。若要获取 Azure 门户中的连接字符串 URL，请转到 Azure 通信服务资源。在资源菜单中，选择“键”，然后选择“连接字符串”。选择“复制”图标以复制连接字符串。
输入连接的名称。
选择“显示高级选项”，然后选择令牌范围。该操作将在指定范围内生成访问令牌及其到期时间。此操作还会生成用作通信服务用户标识的用户 ID。
在“令牌范围项”中，选择“聊天”。
选择创建。此时将显示用户 ID 和访问令牌。

创建聊天会话

添加新操作。
在“选择操作”搜索框中，输入通信服务聊天。在操作列表中，选择“创建聊天线程”。
输入通信服务终结点 URL。若要获取 Azure 门户中的终结点 URL，请转到 Azure 通信服务资源。在资源菜单中，选择“键”，然后选择“终结点”。
输入连接的名称。
选择在上一部分生成的访问令牌，然后添加聊天线程主题说明。添加创建的用户并输入参与者的名称。

发送消息

添加新操作。
在“选择操作”搜索框中，输入通信服务聊天。在操作列表中，选择“向聊天线程发送消息”。
输入访问令牌、线程 ID、内容和名称。

列出聊天会话消息

若要验证是否正确发送了消息，请执行以下操作：

添加新操作。
在“选择操作”搜索框中，输入通信服务聊天。在操作列表中，选择“列出聊天线程消息”。
输入访问令牌和线程 ID。

测试逻辑应用

若要手动启动工作流，请在设计器工具栏中选择“运行”。该工作流将创建用户，为该用户颁发访问令牌，然后删除该令牌并删除该用户。有关详细信息，请查看如何运行工作流。

现在，选择“列出聊天线程消息”。在操作输出中，检查已发送的消息。

Screenshot that shows the Azure Communication Services Chat connector Send chat message action results.

清理工作流资源

若要清理逻辑应用工作流和相关资源，请参阅如何清理逻辑应用资源。

清理资源

如果想要清理并删除通信服务订阅，可以删除资源或资源组。删除资源组同时也会删除与之相关联的任何其他资源。了解有关清理资源的详细信息。

后续步骤

在此快速入门中，你学习了如何：

创建聊天客户端
创建有两个用户参与的会话
向会话发送消息
从会话接收消息
从会话删除用户

试用聊天英雄应用

你可能还想要：

通过

快速入门：向应用中添加聊天

先决条件

设置

添加扩展

登录 Azure CLI

（可选）使用 Azure CLI 标识操作，而无需传入终结点或访问令牌

将终结点存储在环境变量中

在环境变量中存储你的访问令牌

Operations

启动聊天会话

更新聊天会话的主题

列出所有聊天会话

在聊天会话中发送消息

列出聊天会话中的聊天消息

从聊天会话接收聊天消息

发送阅读回执

将用户作为参与者添加到聊天会话

列出聊天会话中的会话参与者

从聊天会话中删除参与者

先决条件

设置

新建 Web 应用程序

安装包

设置应用框架

创建聊天客户端

运行代码

对象模型

启动聊天会话

获取聊天会话客户端

列出所有聊天会话

向聊天会话发送消息

从聊天会话接收聊天消息

将用户作为参与者添加到聊天会话

列出聊天会话中的用户

从聊天会话中删除用户

订阅实时通知的连接状态

代码示例

先决条件

设置

创建新的 Python 应用程序

安装 SDK

对象模型

创建聊天客户端

启动聊天会话

获取聊天会话客户端

列出所有聊天会话

向聊天会话发送消息

从聊天会话接收聊天消息

发送阅读回执

将用户作为参与者添加到聊天会话

列出聊天会话中的会话参与者

运行代码

代码示例

先决条件

设置

创建新的 Java 应用程序

添加聊天 SDK 的包引用

对象模型

创建聊天客户端

启动聊天会话

列出聊天会话

获取聊天会话客户端

在聊天会话中发送消息

从聊天会话接收聊天消息

发送阅读回执

列出聊天参与者

将用户作为参与者添加到聊天会话

运行代码

代码示例

先决条件

设置

创建新的 Android 应用程序

安装库

在 root build.gradle 的打包选项中排除元文件

（替代方案）通过 Maven 安装库

设置 Azure 函数

设置应用程序常量：

设置占位符

初始化应用程序参数