Клиентская библиотека Azure Communication Chat для JavaScript — версия 1.6.0

2025-06-24

Службы коммуникации Azure для чата позволяют разработчикам добавлять возможности чата в свое приложение. Эта клиентская библиотека используется для управления потоками чата и их пользователями, а также для отправки и получения сообщений чата.

Дополнительные сведения о службах коммуникации Azure см. здесь

Начало работы

Необходимые условия

подписка Azure.
Существующий ресурс служб коммуникации. Если необходимо создать ресурс, можно использовать портал Azure, 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 — это основной интерфейс для разработчиков с помощью этой клиентской библиотеки. Он предоставляет асинхронные методы для создания и удаления потока.

Клиент ChatThread

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

Создание потока с двумя пользователями

Используйте метод 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 позволяет выполнять операции, относящиеся к потоку чата, например обновить раздел потока чата, отправить сообщение, добавить участников в поток чата и т. д.

Вы можете инициализировать новый ChatThreadClient с помощью метода getChatThreadClient ChatClient с существующим идентификатором потока:

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 является результатом отправки сообщения, он содержит идентификатор, который является уникальным идентификатором сообщения.

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
}

Добавление пользователей в поток

После создания потока можно добавить и удалить пользователей из этого потока. Добавив пользователей, вы предоставляете им доступ к отправке сообщений в поток. Сначала необходимо получить новый маркер доступа и удостоверение для этого пользователя. Пользователю потребуется этот маркер доступа, чтобы инициализировать клиент чата. Дополнительные сведения о маркерах здесь: аутентификация в службах коммуникации Azure

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

Удаление пользователей из потока

Как и выше, можно также удалить пользователей из потока. Чтобы удалить, необходимо отслеживать идентификаторы добавленных участников.

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 пользователями
Отправка сообщения в поток
Получение сообщений из потока
Удаление пользователей из потока

Способствует

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.