共用方式為

適用於 JavaScript 的 Azure 通訊聊天用戶端連結庫 - 1.5.0 版

  • 發行項

適用於聊天的 Azure 通訊服務 可讓開發人員將聊天功能新增至其應用程式。 使用此客戶端連結庫來管理聊天線程及其使用者，以及傳送和接收聊天訊息。

在這裡深入瞭解 Azure 通訊服務

開始使用

Prerequisites

安裝

npm install @azure/communication-chat

瀏覽器支援

JavaScript 套件組合

若要在瀏覽器中使用此用戶端連結庫，您必須先使用套件組合器。 如需如何執行這項操作的詳細資訊，請參閱我們的 統合檔。 在 rollup.config.js中，在外掛程式中 cjs 新增下列自定義名稱匯出。


cjs({
  namedExports: {
    events: ["EventEmitter"],
    "@azure/communication-signaling": ["CommunicationSignalingClient", "SignalingClient"],
    "@opentelemetry/api": ["CanonicalCode", "SpanKind", "TraceFlags"]
  }
})

重要概念

聊天交談是以對話表示。 對話中的每個用戶稱為聊天參與者。 聊天參與者可以在 1：1 聊天中私下與彼此聊天，或在 1：N 群組聊天中閒聊。 使用者也會在其他人輸入和讀取訊息時，取得近乎即時的更新。

ChatClient

ChatClient 是使用此客戶端連結庫的開發人員的主要介面。 它提供異步方法來建立和刪除線程。

ChatThreadClient

ChatThreadClient 提供異步方法，以在聊天對話內執行訊息和聊天參與者作業。

範例

初始化 ChatClient

使用資源 URL 和使用者存取令牌來初始化聊天用戶端。

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

// Your unique Azure Communication service endpoint
const endpointUrl = '<ENDPOINT>';
const userAccessToken = '<USER_ACCESS_TOKEN>';
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);

建立有兩個使用者的對話

使用 createThread 方法來建立聊天對話。

createChatThreadRequest 會用來描述對話要求：

  • 使用 topic 來提供線程主題;

createChatThreadOptions 用來設定選擇性參數來建立線程：

  • 用來 participants 列出要新增至對話的聊天參與者;
  • 使用 idempotencyToken 指定可重複的要求

createChatThreadResult 是從建立線程傳回的結果。 它包含 chatThread 的 是已建立的線程，以及 errors 屬性，如果參與者無法新增至線程，則會包含無效參與者的相關信息。

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;

建立 ChatThreadClient

ChatThreadClient 可讓您執行聊天對話特定的作業，例如更新聊天對話主題、傳送訊息、將參與者新增至聊天對話等等。

您可以使用具有現有線程標識符的 ChatClient 方法，初始化新的 ChatThreadClient getChatThreadClient ：

const chatThreadClient = chatClient.getChatThreadClient(threadId);

將訊息傳送至對話

使用 sendMessage 方法，將訊息傳送至 threadId 所識別的線程。

sendMessageRequest 用來描述訊息要求：

  • 使用 content 來提供聊天訊息內容；

sendMessageOptions 用來描述工作選擇性參數：

  • 使用 senderDisplayName 指定傳送者的顯示名稱；
  • 用來 type 指定訊息類型，例如 'text' 或 'html' ;

sendChatMessageResult 是從傳送訊息傳回的結果，其中包含標識符，這是訊息的唯一標識符。

const sendMessageRequest =
{
  content: 'Hello Geeta! Can you share the deck for the conference?'
};
const sendMessageOptions:SendMessageOptions = {
  senderDisplayName: "Jack",
  type: "text"
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;

從對話接收訊息

使用即時信號時，您可以訂閱並接聽新的傳入訊息，並據以更新記憶體中的目前訊息。


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

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

for await (const chatMessage of chatThreadClient.listMessages()) {
   // your code here
}

將使用者新增至線程

建立線程之後，您就可以從該線程新增和移除使用者。 藉由新增使用者，您可以讓他們存取權，以便將訊息傳送至線程。 您必須從取得該使用者的新存取令牌和身分識別開始。 使用者將需要該存取權杖，才能初始化其聊天用戶端。 如需令牌的詳細資訊，請參閱這裡：向 Azure 通訊服務 進行驗證


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

await chatThreadClient.addParticipants(addParticipantsRequest);

移除對話中的使用者

與上述類似，您也可以從線程中移除使用者。 若要移除，您必須追蹤您所新增參與者的標識碼。


await chatThreadClient.removeParticipant({ communicationUserId: '<MEMBER_ID>' });

訂閱即時通知的連線狀態

事件的 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
});

疑難排解

下一步

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

  • 建立聊天用戶端
  • 建立具有2位用戶的線程
  • 將訊息傳送至對話
  • 從對話接收訊息
  • 移除對話中的使用者

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。