快速入門：將聊天新增至您的應用程式

發行項
10/30/2023

使用通訊服務聊天 SDK 將即時聊天新增至您的應用程式，開始使用 Azure 通訊服務。在本快速入門中，我們將使用聊天 SDK 來建立聊天線程，讓使用者能夠彼此交談。若要深入瞭解聊天概念，請流覽聊天概念檔。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
作用中的通訊服務資源和連接字串。建立通訊服務資源。
安裝 Azure CLI。
記下您的通訊服務資源端點。您可以從Azure 入口網站取得端點。或者，您可以在連接字串中找到端點 URL。這是之後 endpoint= 的 URL，並以開頭 https:// 。
使用者存取權杖。請務必將範圍設定為聊天，並 記下權杖字串以及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 或殼層，才能存取變數。

編輯您的 .bash_profile ，並新增環境變數：

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

新增環境變數之後，請從主控台視窗執行 source ~/.bash_profile ，讓變更生效。如果您已開啟 IDE 建立環境變數，您可能需要關閉並重新開啟編輯器、IDE 或殼層，才能存取變數。

將您的存取權杖儲存在環境變數中

您可以將環境變數設定 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> 為您的聊天對話識別碼。
將取代 <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> 為您的聊天對話識別碼。
使用 <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> 為您的聊天對話識別碼。
選擇性 <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> 為您的聊天對話識別碼。
將取代 <messageId> 為您想要擷取之訊息的識別碼。
將取代 <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> 為您的聊天對話識別碼。
取代 <messageId> 以指定目前使用者所讀取之最新訊息的識別碼。
將取代 <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> 為您的聊天對話識別碼。
將取代 <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> 為您的聊天對話識別碼。
選擇性 <skip> 地將參與者略過回應中指定的位置。
將取代 <endpoint> 為您的Azure 通訊服務端點。
以先前取得的存取權杖取代 <token> 為執行 identity token issue 命令。

從聊天對話中移除參與者

您可以使用「參與者移除」命令，從聊天對話中移除聊天參與者。

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

將取代 <chatThreadId> 為您的聊天對話識別碼。
將取代 <userId> 為您想要從聊天對話中移除的 userId。
將取代 <endpoint> 為您的Azure 通訊服務端點。
以先前取得的存取權杖取代 <token> 為執行 identity token issue 命令。

必要條件

開始之前，請務必：

建立具有作用中訂用帳戶的 Azure 帳戶。如需詳細資訊，請參閱免費建立帳戶。
安裝 Node.js Active LTS 和維護 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 檔案中的 相依性。

設定應用程式架構

本快速入門會使用包裹來組合應用程式資產。執行下列命令來安裝它，並將它列為 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!

物件模型

下列類別和介面會處理 Azure 通訊服務 Chat SDK for JavaScript 的一些主要功能。

名稱	描述
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 是現有聊天對話的唯一識別碼。

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

新增此程式碼以取代 <CREATE CHAT THREAD CLIENT> client.js 中的批註、重新整理瀏覽器索引標籤並檢查主控台，您應該會看到：

Chat Thread client for threadId: <threadId>

列出所有聊天線程

方法會 listChatThreads 傳 PagedAsyncIterableIterator 回型別 ChatThreadItem 的。它可用於列出所有聊天線程。的反覆運算器 [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 是從傳送訊息傳回的回應，其中包含識別碼，這是訊息的唯一識別碼。

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}`);

新增此程式碼以取代 <SEND MESSAGE TO A CHAT THREAD> client.js 中的批註、重新整理瀏覽器索引標籤並檢查主控台。

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
});

新增此程式碼以取代 <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> client.js 中的批註。重新整理瀏覽器索引標籤，您應該會在主控台中看到訊息 Notification chatMessageReceived ;

或者，您可以藉由以指定的間隔輪詢 listMessages 方法來擷取聊天訊息。


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

新增此程式碼以取代 <LIST MESSAGES IN A CHAT THREAD> client.js 中的批註。重新整理索引標籤，在主控台中，您應該會找到在此聊天對話中傳送的訊息清單。

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取代 為新的使用者識別碼新增此程式碼以取代 <ADD NEW PARTICIPANT TO THREAD> client.js 中的批註

列出聊天對話中的使用者

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

新增此程式碼以取代 <LIST PARTICIPANTS IN A THREAD> client.js 中的批註、重新整理瀏覽器索引標籤並檢查主控台，您應該會線上程中看到使用者的相關資訊。

從聊天對話中移除使用者

與新增參與者類似，您可以從聊天對話中移除參與者。若要移除，您必須追蹤您所新增參與者的識別碼。

使用 removeParticipant 方法，其中 participant 是要從執行緒中移除的通訊使用者。


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

將PARTICIPANT_ID 取代為上一個步驟中使用的使用者識別碼（ < NEW_PARTICIPANT_USER_ID > ）。新增此程式碼以取代 <REMOVE PARTICIPANT FROM THREAD> client.js 中的批註。

事件的 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

物件模型

下列類別和介面會處理 Azure 通訊服務 Chat SDK for Python 的一些主要功能。

名稱	描述
`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 要新增至聊天對話的。會將 ChatParticipantCommunicationUserIdentifier 型別當做 user 。

CreateChatThreadResult 是建立執行緒所傳回的結果。您可以使用它來擷取 id 已建立的聊天對話。 id然後，您可以使用方法來擷取 ChatThreadClient 物件 get_chat_thread_client 。您可以使用 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 是現有聊天對話的唯一識別碼。

您可以使用 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 是從傳送訊息傳回的回應。其中包含識別碼，這是訊息的唯一識別碼。

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 發生訊息的任何編輯或刪除。針對已刪除的訊息，傳 datetime 回值， ChatMessage.deleted_on 指出何時刪除該訊息。針對編輯的訊息， ChatMessage.edited_on 傳 datetime 回值，指出訊息編輯時間。您可以使用存取訊息建立 ChatMessage.created_on 的原始時間，以便用來排序訊息。

list_messages 會傳回不同類型的訊息，可由識別 ChatMessage.type 。

如需詳細資訊，請參閱訊息類型。

傳送讀取收據

您可以使用 send_read_receipt 方法，代表使用者將讀取收據事件張貼至執行緒。

使用 message_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 Development Kit （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

您會發現 'generate' 目標已建立與 artifactId 同名的目錄。在此目錄下， src/main/java directory 包含專案原始程式碼、 src/test/java 目錄包含測試來源，而 pom.xml 檔案是專案的 Project 物件模型或 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>

物件模型

下列類別和介面會處理 Azure 通訊服務 Chat SDK for JAVA 的一些主要功能。

名稱	描述
ChatClient	聊天功能需要這個類別。您可以使用您的訂用帳戶資訊將其具現化，並用它來建立、取得和刪除線程。
ChatAsyncClient	非同步聊天功能需要這個類別。您可以使用您的訂用帳戶資訊將其具現化，並用它來建立、取得和刪除線程。
ChatThreadClient	聊天對話功能需要這個類別。您可以透過 ChatClient 取得實例，並用它來傳送/接收/更新/刪除訊息、新增/移除/取得使用者、傳送輸入通知和讀取回條。
ChatThreadAsyncClient	非同步 Chat Thread 功能需要這個類別。您可以透過 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 是建立聊天對話所傳回的回應。它包含 getChatThread() 方法，其會傳回 ChatThread 物件，可用來取得執行緒用戶端，您可以在建立的執行緒上取得 ChatThreadClient 執行作業的：新增參與者、傳送訊息等。 ChatThread 物件也包含 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 是現有聊天對話的唯一識別碼。

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

將訊息傳送至聊天對話

使用方法， sendMessage 將訊息傳送至您建立的執行緒，由 chatThreadId 識別。 sendChatMessageOptions 用來描述聊天訊息要求。

使用 content 提供聊天訊息內容。
使用 type 來指定聊天訊息內容類型、TEXT 或 HTML。
使用 senderDisplayName 來指定寄件者的顯示名稱。
選擇性 metadata 地包含您想要連同訊息一起傳送的任何其他資料。此欄位提供一種機制，可讓開發人員擴充聊天訊息功能，並為使用案例新增自訂資訊。例如，在訊息中共用檔案連結時，您可能會想要在中繼資料中新增 hasAttachment:true ，讓收件者的應用程式可以剖析該檔案並據以顯示。

回應 sendChatMessageResult 包含，這是訊息的唯一 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() 發生訊息的任何編輯或刪除。針對已刪除的訊息，會傳回 datetime 值， chatMessage.getDeletedOn() 指出刪除該訊息的時間。針對編輯的訊息， chatMessage.getEditedOn() 會傳回日期時間，指出訊息編輯的時間。訊息建立的原始時間可以使用來存取 chatMessage.getCreatedOn() ，而且可用於排序訊息。

在這裡深入瞭解訊息類型：訊息類型。

傳送讀取收據

sendReadReceipt使用方法，代表使用者將讀取回條事件張貼至聊天對話。 chatMessageId 是已讀取之聊天訊息的唯一識別碼。

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'

請參閱 https://search.maven.org/artifact/com.azure.android/azure-communication-common 和 https://search.maven.org/artifact/com.azure.android/azure-communication-chat 以取得最新版本號碼。

排除根 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 建置系統將程式庫匯入您的專案，請將它新增至 dependencies 應用程式的 pom.xml 檔案區段，並指定其成品識別碼和您想要使用的版本：

<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 Function 整合，以避免硬式編碼應用程式參數。

設定應用程式常數：

建立會儲存所有應用程式常數的類別 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_ENDPOINTFIRST_USER_ACCESS_TOKEN和 FIRST_USER_ID 會從呼叫 Azure Function 傳回。如需詳細資訊，請參閱 Azure 函式整合。我們會使用呼叫 Azure Function 的回應來初始化參數清單：

ACS_ENDPOINT：通訊服務資源的端點。
FIRST_USER_ID 和 SECOND_USER_ID ：通訊服務資源所產生的有效通訊服務使用者識別碼。
FIRST_USER_ACCESS_TOKEN：的 <FIRST_USER_ID> 通訊服務存取權杖。

呼叫 Azure Function 來初始化應用程式參數的程式碼區塊：

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();

物件模型

下列類別和介面會處理 Azure 通訊服務 Chat SDK for JavaScript 的一些主要功能。

名稱	描述
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

Install the package

安裝適用于 .NET 的 Azure 通訊聊天 SDK

dotnet add package Azure.Communication.Chat

物件模型

下列類別會處理 Azure 通訊服務 Chat SDK for C# 的一些主要功能。

名稱	描述
ChatClient	聊天功能需要這個類別。您可以使用您的訂用帳戶資訊將其具現化，並用它來建立、取得和刪除線程。
ChatThreadClient	聊天對話功能需要這個類別。您可以透過 ChatClient 取得實例，並用它來傳送/接收/更新/刪除訊息、新增/移除/取得參與者、傳送輸入通知和讀取回條。

建立聊天用戶端

若要建立聊天用戶端，您將使用通訊服務端點和在必要條件步驟中產生的存取權杖。您必須使用 CommunicationIdentityClient Identity SDK 中的類別來建立使用者，併發出權杖以傳遞至聊天用戶端。

深入瞭解使用者存取權杖。

本快速入門並未說明如何建立服務層級來管理聊天應用程式的權杖，不過建議您這麼做。深入瞭解聊天架構

複製下列程式碼片段並貼到原始程式檔： 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);
        }
    }
}

啟動聊天對話

createChatThread使用 chatClient 上的方法來建立聊天對話

用來 topic 提供此聊天的主題;使用函式建立 UpdateTopic 聊天對話之後，即可更新主題。
使用 participants 屬性傳遞要新增至聊天對話的物件清單 ChatParticipant 。物件 ChatParticipant 會使用 CommunicationIdentifier 物件初始化。 CommunicationIdentifier可以是、或 PhoneNumberIdentifier 類型 CommunicationUserIdentifierMicrosoftTeamsUserIdentifier 。例如，若要取得 CommunicationIdentifier 物件，您必須依照建立使用者的指示傳遞您所建立的存取識別碼

來自方法的 createChatThread 回應物件包含 chatThread 詳細資料。若要與聊天對話作業互動，例如新增參與者、傳送訊息、刪除訊息等， chatThreadClient 用戶端實例必須使用用戶端上的 ChatClient 方法具現化 GetChatThreadClient 。

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 是現有聊天對話的唯一識別碼。

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 發生訊息的任何編輯或刪除。針對已刪除的訊息，會傳回 datetime 值， chatMessage.DeletedOn 指出刪除該訊息的時間。針對編輯的訊息， chatMessage.EditedOn 會傳回日期時間，指出訊息編輯的時間。訊息建立的原始時間可以使用來存取 chatMessage.CreatedOn ，而且可用於排序訊息。

GetMessages會傳回不同類型的訊息，這些訊息可由識別。 chatMessage.Type 這些類型包括：

Text：執行緒成員傳送的一般聊天訊息。
Html：格式化的文字訊息。請注意，通訊服務使用者目前無法傳送 RichText 訊息。從 Teams 使用者傳送至 Teams Interop 案例中的通訊服務使用者的郵件支援此訊息類型。
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 應用程式委派 作為生命週期，以及 Swift 作為語言。

選取 [ 下一步 ]，然後選擇您要在其中建立專案的目錄。

安裝程式庫

使用 CocoaPods 安裝必要的通訊服務相依性。

從命令列，移至 iOS 專案的根目錄 ChatQuickstart 。使用下列命令建立 Podfile： pod init 。

開啟 Podfile，並將下列相依性新增至 ChatQuickstart 目標：

pod 'AzureCommunicationChat', '~> 1.3.4'

使用下列命令安裝相依性： pod install 。請注意，這也會建立 Xcode 工作區。

執行 pod install 之後，選取新建立 .xcworkspace 的專案，以 Xcode 重新開啟專案。

設定預留位置

在 Xcode 中開啟工作區 ChatQuickstart.xcworkspace ，然後開啟 ViewController.swift 。

在本快速入門中，您會將程式碼新增至 viewController ，並在 Xcode 主控台中檢視輸出。本快速入門無法解決在 iOS 中建置使用者介面的問題。

在頂端 viewController.swift ，匯入和 AzureCommunicatonChat 連結 AzureCommunication 庫：

import AzureCommunicationCommon
import AzureCommunicationChat

將下列程式碼複製到 viewDidLoad() 的方法 ViewController ：

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 通訊服務 Chat 程式庫，將預留位置取代為範例程式碼。

建立聊天用戶端

若要建立聊天用戶端，您將使用通訊服務端點和在必要條件步驟中產生的存取權杖。

深入瞭解使用者存取權杖。

本快速入門並未說明如何建立服務層級來管理聊天應用程式的權杖，不過建議您這麼做。深入瞭解聊天架構

將批註 <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 通訊服務 Chat 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> 為有效的通訊服務使用者識別碼。

您在這裡使用號志等候完成處理常式，然後再繼續。在後續步驟中，您將使用 threadId 從傳回至完成處理常式之回應的。

列出所有聊天線程

建立聊天對話之後，我們可以呼叫 listChatThreads 上的 ChatClient 方法來列出所有聊天線程。以下列程式碼取代 <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 是現有聊天對話的唯一識別碼。

以下列程式碼取代 <GET A CHAT THREAD CLIENT> 註解：

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

將訊息傳送至聊天對話

send使用方法，將訊息傳送至 threadId 所識別的執行緒。

SendChatMessageRequest 用來描述訊息要求：

用來 content 提供聊天訊息內容
用來 senderDisplayName 指定寄件者的顯示名稱
使用 type 來指定訊息類型，例如 'text' 或 'html'
選擇性 metadata 地包含您想要連同訊息一起傳送的任何其他資料。此欄位提供一種機制，可讓開發人員擴充聊天訊息功能，並為使用案例新增自訂資訊。例如，在訊息中共用檔案連結時，您可能會想要在中繼資料中新增 'hasAttachment：true'，讓收件者的應用程式可以剖析並據以顯示。

SendChatMessageResult 是從傳送訊息傳回的回應，其中包含識別碼，這是訊息的唯一識別碼。

將批註 <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 是已讀取之聊天訊息的唯一識別碼。

將批註 <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 之前，請確定您已取得該使用者的新存取權杖和身分識別。使用者需要該存取權杖，才能初始化其聊天用戶端。

add使用的 ChatThreadClient 方法，將一或多個參與者新增至聊天對話。以下是每個執行緒參與者的支援屬性：

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> 為要新增之使用者的通訊服務使用者識別碼。

列出執行緒中的使用者

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 Logic Apps 資源，或使用您想要使用的觸發程式建立空白邏輯應用程式。通訊服務聊天連接器目前只提供動作，因此您的邏輯應用程式至少需要觸發程式。

建立使用者

在 Power Automate 中完成這些步驟，並在編輯模式中開啟 Power Automate 流程。

若要使用通訊服務識別連接器在工作流程中新增步驟：

在設計工具中，在您要新增動作的步驟下，選取 [ 新增步驟 ]。或者，若要在步驟之間新增動作，請將指標移至這些步驟之間的箭號上方，選取加號（+），然後選取 [ 新增動作 ]。
在 [ 選擇作業 搜尋] 方塊中，輸入 通訊服務身分 識別。在動作清單中，選取 [ 建立使用者 ]。
輸入連接字串。若要取得Azure 入口網站中的連接字串 URL，請移至Azure 通訊服務資源。在資源功能表中，選取 [金鑰 ]，然後選取 [連線ion 字串 ]。選取複製圖示以複製連接字串。
輸入連接的名稱
選取 [ 顯示進階選項 ]，然後選取權杖範圍。動作會產生存取權杖及其具有指定範圍的到期時間。此動作也會產生通訊服務使用者身分識別的使用者識別碼。
在 [權杖範圍專案 ] 中，選取 [聊天 ]。
選取建立。會顯示使用者識別碼和存取權杖。

建立聊天對話

新增動作。
在 [ 選擇作業 搜尋] 方塊中，輸入 通訊服務聊天 。在動作清單中，選取 [ 建立聊天對話 ]。
輸入通訊服務端點 URL。若要取得Azure 入口網站中的端點 URL，請移至Azure 通訊服務資源。在資源功能表中，選取 [金鑰 ]，然後選取 [ 端點 ]。
輸入連接的名稱
選取上一節中產生的存取權杖，然後新增聊天交談主旨描述。新增已建立的使用者，並輸入參與者的名稱。

傳送訊息

新增動作。
在 [ 選擇作業 搜尋] 方塊中，輸入 通訊服務聊天 。在動作清單中，選取 [ 將訊息傳送至聊天對話 ]。
輸入存取權杖、執行緒識別碼、內容和名稱。

列出聊天對話訊息

若要確認您已正確傳送訊息：

新增動作。
在 [ 選擇作業 搜尋] 方塊中，輸入 通訊服務聊天 。在動作清單中，選取 [ 列出聊天對話訊息 ]。
輸入存取權杖和執行緒識別碼。

測試邏輯應用程式

若要手動啟動工作流程，請在設計工具工具列上選取 [ 執行 ]。工作流程會建立使用者、發出該使用者的存取權杖，然後移除權杖並刪除使用者。如需詳細資訊，請參閱如何執行工作流程。

現在，選取 [ 列出聊天對話訊息 ]。在動作輸出中，檢查已傳送的訊息。

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

清除工作流程資源

若要清除邏輯應用程式工作流程和相關資源，請檢閱如何清除 Logic Apps 資源。

清除資源

如果您想要清除並移除通訊服務訂用帳戶，您可以刪除資源或資源群組。刪除資源群組也會刪除與其相關聯的任何其他資源。深入瞭解清除資源。

下一步

在本快速入門中，您已瞭解如何：

建立聊天用戶端
建立具有兩個使用者的執行緒
將訊息傳送至執行緒
從執行緒接收訊息
從執行緒移除使用者

試用聊天主圖應用程式

您可能也想要：

開始使用 UI 連結庫
瞭解聊天概念
熟悉聊天 SDK
在 React Native 應用程式中使用聊天 SDK。

快速入門：將聊天新增至您的應用程式

必要條件

設定

新增擴充功能

登入 Azure CLI

（選擇性）使用 Azure CLI 身分識別作業而不傳入端點或存取權杖

將您的端點儲存在環境變數中

將您的存取權杖儲存在環境變數中

Operations

啟動聊天對話

更新聊天對話的主題

列出所有聊天線程

將訊息傳送至聊天對話

列出聊天對話中的聊天訊息

從聊天對話接收聊天訊息

傳送讀取收據

將使用者新增為參與者至聊天對話

列出聊天對話中的執行緒參與者

從聊天對話中移除參與者

必要條件

設定

建立新的 Web 應用程式

安裝套件

設定應用程式架構

建立聊天用戶端

執行程式碼

物件模型

啟動聊天對話

取得聊天對話用戶端

列出所有聊天線程

將訊息傳送至聊天對話

從聊天對話接收聊天訊息

將使用者新增為參與者至聊天對話

列出聊天對話中的使用者

從聊天對話中移除使用者

訂閱即時通知的線上狀態

範例程式碼

必要條件

設定

建立新的 Python 應用程式

安裝 SDK

物件模型

建立聊天用戶端

啟動聊天對話

取得聊天對話用戶端

列出所有聊天線程

將訊息傳送至聊天對話

從聊天對話接收聊天訊息

傳送讀取收據

將使用者新增為參與者至聊天對話

列出聊天對話中的執行緒參與者

執行程式碼

範例程式碼

必要條件

設定

建立新的 JAVA 應用程式

新增聊天 SDK 的套件參考

物件模型

建立聊天用戶端

啟動聊天對話

列出聊天線程

取得聊天對話用戶端

將訊息傳送至聊天對話

從聊天對話接收聊天訊息

傳送讀取收據

列出聊天參與者

將使用者新增為聊天對話的參與者

執行程式碼

範例程式碼

必要條件

設定

建立新的 Android 應用程式

安裝程式庫

排除根 build.gradle 中封裝選項中的中繼檔案

（替代）透過 Maven 安裝程式庫

設定 Azure 函式

設定應用程式常數：

設定預留位置

初始化應用程式參數

建立聊天用戶端