JavaScript 用 Azure Communication Chat クライアントライブラリ - バージョン 1.6.0

2025-06-24

Azure Communication Services for Chat を使用すると、開発者はアプリにチャット機能を追加できます。このクライアントライブラリを使用して、チャットスレッドとそのユーザーを管理し、チャットメッセージを送受信します。

Azure Communication Services の詳細については、

はじめ

前提条件

Azure サブスクリプション。
既存の Communication Services リソース。リソースを作成する必要がある場合は、Azure Portal、Azure PowerShell、または Azure CLIを使用できます。
Node.js

装着

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 は、このクライアントライブラリを使用する開発者向けの主要なインターフェイスです。スレッドを作成および削除するための非同期メソッドが用意されています。

チャットスレッドクライアント

ChatThreadClient は、チャットスレッド内でメッセージとチャット参加者の操作を行う非同期メソッドを提供します。

例

ChatClient の初期化

リソース URL とユーザーアクセストークンを使用して、チャットクライアントを初期化します。

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

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

2 人のユーザーを含むスレッドを作成する

createThread メソッドを使用してチャットスレッドを作成します。

createChatThreadRequest は、スレッド要求を記述するために使用されます。

topic を使用してスレッドトピックを指定します。

createChatThreadOptions は、スレッドを作成するための省略可能なパラメーターを設定するために使用されます。

participants を使用して、スレッドに追加するチャット参加者を一覧表示します。
idempotencyToken を使用して反復可能な要求を指定する

createChatThreadResult は、スレッドの作成から返される結果です。これには、作成されたスレッドである chatThread と、スレッドに追加できなかった場合に無効な参加者に関する情報を含む errors プロパティが含まれます。

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

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

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 を使用すると、チャットスレッドトピックの更新、メッセージの送信、チャットスレッドへの参加者の追加など、チャットスレッドに固有の操作を実行できます。

既存のスレッド ID で ChatClient の getChatThreadClient メソッドを使用して、新しい ChatThreadClient を初期化できます。

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

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

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

スレッドにメッセージを送信する

sendMessage メソッドを使用して、threadId で識別されたスレッドにメッセージを送信します。

sendMessageRequest は、メッセージ要求を記述するために使用されます。

content を使用してチャットメッセージの内容を提供します。

sendMessageOptions は、操作の省略可能なパラメーターを記述するために使用されます。

senderDisplayName を使用して、送信者の表示名を指定します。
type を使用して、"text" や "html" などのメッセージの種類を指定します。

sendChatMessageResult メッセージの送信から返された結果であり、メッセージの一意の ID である ID が含まれます。

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

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

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

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;

スレッドからメッセージを受信する

リアルタイムシグナリングを使用すると、サブスクライブして新しい受信メッセージをリッスンし、それに応じてメモリ内の現在のメッセージを更新できます。

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

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

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

または、指定した間隔で listMessages メソッドをポーリングしてチャットメッセージを取得することもできます。

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

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

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

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

スレッドへのユーザーの追加

スレッドが作成されたら、そのスレッドに対してユーザーを追加および削除できます。ユーザーを追加することで、スレッドにメッセージを送信できるアクセス権をユーザーに付与します。まず、そのユーザーの新しいアクセストークンと ID を取得する必要があります。ユーザーは、チャットクライアントを初期化するために、そのアクセストークンが必要になります。トークンの詳細については、こちら: Azure Communication Services に対する認証の

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

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

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

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

await chatThreadClient.addParticipants(addParticipantsRequest);

スレッドからユーザーを削除する

上記と同様に、スレッドからユーザーを削除することもできます。削除するには、追加した参加者の ID を追跡する必要があります。

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

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

const chatThreadClient = chatClient.getChatThreadClient("<threadId>");

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

イベント realTimeNotificationConnected および realTimeNotificationDisconnected へのサブスクリプションを使用すると、呼び出しサーバーへの接続がアクティブなタイミングを把握できます。

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

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

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

トラブルシューティング

ロギング（記録）

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。または、setLogLevelで @azure/logger を呼び出すことによって、実行時にログを有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

次の手順

このクイックスタートでは、次の方法を学習しました。

チャットクライアントを作成する
2 人のユーザーでスレッドを作成する
スレッドにメッセージを送信する
スレッドからメッセージを受信する
スレッドからユーザーを削除する

貢献

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。