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

發行項
04/28/2024

使用 Azure 通訊服務的聊天 SDK，將即時聊天加入您的應用程式，以開始使用 Azure 通訊服務。在本快速入門中，我們將使用聊天 SDK 來建立聊天對話，讓使用者可以彼此聊天。若要深入瞭解「聊天」的概念，請造訪聊天概念文件。

必要條件

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

從聊天對話中移除參與者

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

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 作用中 LTS 和維修 LTS 版本。
建立 Azure 通訊服務資源。如需詳細資訊，請參閱建立 Azure 通訊服務資源。您必須在本快速入門中記錄您的資源端點和連接字串。
建立三個 Azure 通訊服務使用者，並為其核發使用者存取權杖。請務必將範圍設定為 chat，並記下 token 字串和 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 通訊服務端點，以及在必要條件步驟中所產生的存取權杖。

使用者存取權杖可讓您建立直接向 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 是現有聊天對話的唯一識別碼。

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 是傳送訊息時的傳回回應，包含的識別碼就是訊息的唯一識別碼。

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 取代為新的使用者識別碼。新增此程式碼來取代 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> 註解，重新整理您的瀏覽器索引標籤並查看主控台，您應該會看到對話中使用者的相關資訊。

從聊天對話中移除使用者

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

使用 removeParticipant 方法，其中 participant 是要從對話中移除的通訊使用者。


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

將 PARTICIPANT_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 通訊服務資源。如需詳細資訊，請參閱快速入門：建立和管理通訊服務資源。您必須在本快速入門中記錄您的資源端點和連接字串。
使用者存取權杖。請務必將範圍設定為 chat，並記下 token 字串和 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 是現有聊天對話的唯一識別碼。

您可以使用 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 對訊息所做的任何編輯或刪除。針對已刪除的訊息，ChatMessage.deleted_on 會傳回 datetime 值，指出刪除該訊息的時間。針對已編輯的訊息，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 通訊服務資源。您必須在本快速入門中記錄您的資源端點和連接字串。
使用者存取權杖。請務必將範圍設定為 chat，並記下 token 字串和 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 檔案是專案的「專案物件模型」(簡稱 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 通訊服務端點，以及在必要條件步驟中所產生的存取權杖。使用者存取權杖可讓您建立直接向 Azure 通訊服務進行驗證的用戶端應用程式。一旦您在伺服器上產生這些權杖，請將其傳回給用戶端裝置。您必須使用一般 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() 對訊息所做的任何編輯或刪除。若為已刪除的訊息，chatMessage.getDeletedOn() 會傳回 datetime 值，指出刪除該訊息的時間。若為編輯過的訊息，chatMessage.getEditedOn() 會傳回 datetime 值，指出編輯該訊息的時間。可以使用 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 通訊服務資源。您必須在本快速入門中記錄您的資源端點和連接字串。
建立兩個 Azure 通訊服務使用者，並為其核發使用者存取權杖。請務必將範圍設定為 chat，並記下 token 字串和 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'

排除根 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 區段，指定其成品識別碼和您想要使用的版本：

<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：通訊服務資源所產生的有效通訊服務使用者識別碼。
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 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> 取代為下列程式碼 (在檔案頂端放置匯入陳述式)：


// 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 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 通訊服務資源。您必須在本快速入門中記錄您的資源端點和連接字串。
使用者存取權杖。請務必將範圍設定為 chat，並記下 token 字串和 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

物件模型

下列類別會處理適用於 C# 的 Azure 通訊服務聊天 SDK 的一些主要功能。

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

建立聊天用戶端

若要建立聊天用戶端，您將使用您的 Azure 通訊服務端點，以及在必要條件步驟中所產生的存取權杖。您必須使用身分識別 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 物件清單。 ChatParticipant 物件要以 CommunicationIdentifier 物件初始化。 CommunicationIdentifier 可以是 CommunicationUserIdentifier、MicrosoftTeamsUserIdentifier 或 PhoneNumberIdentifier 類型。例如，若要取得 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 來提供訊息的內容，這是必要項目。
針對訊息內容類型 (例如 'Text' 或 'Html') 使用 type。如果未指定，則會設定 '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 參數。如果指定該位移，您就會收到在它之後接收、更新或刪除的訊息。請注意，在 offset 時間之前收到，但在此時間之後被編輯或移除的訊息，也一樣會傳回。

GetMessages 會傳回訊息的最新版本，包括使用 UpdateMessage 和 DeleteMessage 對訊息所做的任何編輯或刪除。若為已刪除的訊息，chatMessage.DeletedOn 會傳回 datetime 值，指出刪除該訊息的時間。若為編輯過的訊息，chatMessage.EditedOn 會傳回 datetime 值，指出編輯該訊息的時間。可以使用 chatMessage.CreatedOn 來存取訊息建立的原始時間，且可以用來排序訊息。

GetMessages 會傳回不同訊息類型 (可用 chatMessage.Type 識別)。這些類型包括：

Text：由對話成員傳送的一般聊天訊息。
Html：格式化的文字訊息。請注意，通訊服務使用者目前無法傳送 RichText 訊息。在 Teams 互通性案例中，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 通訊服務中建立兩個使用者，並為其核發使用者存取權杖。請務必將範圍設定為 chat，並記下 token 字串和 user_id 字串。在本快速入門中，您會建立具有初始參與者的對話，然後將第二個參與者新增至對話。您也可以使用 Azure CLI，並以您的連接字串執行下列命令以建立使用者和存取權杖。
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
如需詳細資訊，請參閱使用 Azure CLI 建立和管理存取權杖。

設定

建立新的 iOS 應用程式

開啟 Xcode，然後選取 [Create a new Xcode project] \(建立新的 Xcode 專案\)。然後選取 [iOS] 作為平台，選取 [App] 作為範本。

針對專案名稱，輸入 ChatQuickstart。然後選取 [Storyboard] 作為介面，選取 [UIKit 應用程式委派] 作為生命週期，以及選取 [Swift] 作為語言。

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

安裝程式庫

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

從命令列移至 ChatQuickstart iOS 專案的根目錄內。使用下列命令建立 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 頂端，匯入 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 通訊服務聊天程式庫，將預留位置取代為範例程式碼。

建立聊天用戶端

若要建立聊天用戶端，您將使用您的 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> 取代為有效的通訊服務使用者識別碼。

您在這裡使用旗號等候完成處理常式，然後再繼續。在後續步驟中，您將會使用傳回至完成處理常式的回應 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 是現有聊天對話的唯一識別碼。

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

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

列出對話中的使用者

使用 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 通訊服務資源。在資源選單中，選取 [金鑰]，然後選取 [連接字串]。選取複製圖示以複製連接字串。
輸入連接的名稱
選取 [顯示進階選項]，接著選取權杖範圍。動作會產生存取權杖及其具有指定範圍的到期時間。此動作也會產生通訊服務使用者身分識別的使用者識別碼。
在 [權杖範圍項目] 中，選取 [聊天]。
選取建立。會顯示使用者識別碼和存取權杖。

建立聊天對話

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

傳送訊息

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

列出聊天對話訊息

若要確認您是否正確傳送訊息：

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

測試應用程式邏輯

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

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

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

清除工作流程資源

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

清除資源

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

下一步

在此快速入門中，您已了解如何：

建立聊天用戶端
建立有兩個使用者的對話
將訊息傳送至對話
從對話接收訊息
移除對話中的使用者

試用聊天 Hero 應用程式

您可能也會想要：

開始使用 UI 程式庫
深入了解聊天概念
熟悉聊天 SDK
使用 React Native 中的聊天 SDK 應用程式。

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

必要條件

設定

新增延伸模組

登入 Azure CLI

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

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

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

Operations

開始聊天對話

更新聊天對話的主題

列出所有聊天對話

將訊息傳送至聊天對話

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

從聊天對話接收聊天訊息

傳送讀取回條

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

列出聊天對話中的對話參與者

從聊天對話中移除參與者

必要條件

設定

建立新的 Web 應用程式

安裝套件

設定應用程式架構

建立聊天用戶端

執行程式碼

物件模型

開始聊天對話

取得聊天對話用戶端

列出所有聊天對話

將訊息傳送至聊天對話

從聊天對話接收聊天訊息

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

列出聊天對話中的使用者

從聊天對話中移除使用者

訂閱即時通知的連線狀態

範例程式碼

必要條件

設定

建立新的 Python 應用程式

安裝 SDK

物件模型

建立聊天用戶端

開始聊天對話

取得聊天對話用戶端

列出所有聊天對話

將訊息傳送至聊天對話

從聊天對話接收聊天訊息

傳送讀取回條

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

列出聊天對話中的對話參與者

執行程式碼

範例程式碼

必要條件

設定

建立新的 Java 應用程式

新增聊天 SDK 的套件參考

物件模型

建立聊天用戶端

開始聊天對話

列出聊天對話

取得聊天對話用戶端

將訊息傳送至聊天對話

從聊天對話接收聊天訊息

傳送讀取回條

列出聊天參與者

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

執行程式碼

範例程式碼

必要條件

設定

建立新的 Android 應用程式

安裝程式庫

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

(替代方法) 透過 Maven 安裝程式庫

設定 Azure 函式

設定應用程式常數：

設定預留位置

初始化應用程式參數

建立聊天用戶端