Biblioteca de clientes do Chat de Comunicação do Azure para JavaScript – versão 1.6.0

Os Serviços de Comunicação do Azure para Chat permitem que os desenvolvedores adicionem recursos de chat ao aplicativo. Use essa biblioteca de clientes para gerenciar threads de chat e seus usuários e enviar e receber mensagens de chat.

Leia mais sobre os Serviços de Comunicação do Azure aqui

Introdução

Pré-requisitos

• Uma assinatura do Azure.
• Um recurso existente dos Serviços de Comunicação. Se você precisar criar o recurso, poderá usar o Portal do Azure, o do Azure PowerShell ou a CLI do Azure .
• Node.js

Instalar

npm install @azure/communication-chat

Suporte ao navegador

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento . Em rollup.config.js, adicione as seguintes exportações de nome personalizado no plug-in cjs.

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

Principais conceitos

Uma conversa de chat é representada por um thread. Cada usuário no thread é chamado de participante do chat. Os participantes do chat podem conversar entre si em particular em um chat 1:1 ou se amontoar em um chat em grupo 1:N. Os usuários também recebem atualizações quase em tempo real para quando outras pessoas estão digitando e quando leem as mensagens.

Cliente de bate-papo

ChatClient é a interface principal para desenvolvedores que usam essa biblioteca de clientes. Ele fornece métodos assíncronos para criar e excluir um thread.

ChatThreadClient

ChatThreadClient fornece métodos assíncronos para executar as operações de mensagens e de participantes de chat dentro do thread de chat.

Exemplos

Inicializar o ChatClient

Use a URL do recurso e o token de acesso do usuário para inicializar o cliente de chat.

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

Criar um thread com dois usuários

Use o método createThread para criar um thread de chat.

createChatThreadRequest é usado para descrever a solicitação de thread:

• Use topic para fornecer um tópico de thread;

createChatThreadOptions é usado para definir os parâmetros opcionais para criar o thread:

• Use participants para listar os participantes do chat a serem adicionados ao thread;
• Usar idempotencyToken para especificar uma solicitação repetível

createChatThreadResult é o resultado retornado da criação de um thread. Ele contém um chatThread que é o thread que foi criado, bem como uma propriedade errors que conterá informações sobre participantes inválidos se eles não tiverem sido adicionados ao thread.

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;

Criar um ChatThreadClient

O ChatThreadClient permitirá que você execute operações específicas a um thread de chat, como atualizar o tópico do thread de chat, enviar uma mensagem, adicionar participantes ao thread de chat etc.

Você pode inicializar um novo ChatThreadClient usando o método getChatThreadClient do ChatClient com uma ID de thread existente:

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

Enviar uma mensagem para o thread

Use sendMessage método para enviar uma mensagem para um thread identificado por threadId.

sendMessageRequest é usado para descrever a solicitação de mensagem:

• Use content para fornecer o conteúdo da mensagem de chat;

sendMessageOptions é usado para descrever os parâmetros opcionais da operação:

• Use senderDisplayName para especificar o nome de exibição do remetente;
• Use type para especificar o tipo de mensagem, como 'text' ou 'html' ;

sendChatMessageResult é o resultado retornado do envio de uma mensagem, ele contém uma ID, que é a ID exclusiva da mensagem.

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;

Receber mensagens de um thread

Com a sinalização em tempo real, você pode assinar para ouvir novas mensagens de entrada e atualizar as mensagens atuais na memória adequadamente.

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

Como alternativa, você pode recuperar mensagens de chat sondando o método listMessages em intervalos especificados.

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
}

Adicionar usuários a um thread

Depois que um thread é criado, você pode adicionar e remover usuários desse thread. Ao adicionar usuários, você dá a eles acesso para poder enviar mensagens para o thread. Você precisará começar obtendo um novo token de acesso e uma identidade para esse usuário. O usuário precisará desse token de acesso para inicializar seu cliente de chat. Mais informações sobre tokens aqui: Autenticar nos Serviços de Comunicação do 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);

Remover usuários de um thread

Semelhante ao indicado acima, você também pode remover usuários de um thread. Para remover, você precisará acompanhar as IDs dos participantes adicionados.

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

Assinar o status da conexão de notificações em tempo real

A assinatura de eventos realTimeNotificationConnected e realTimeNotificationDisconnected permite que você saiba quando a conexão com o servidor de chamada está ativa.

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

Solucionando problemas

Registro

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximas etapas

Neste início rápido, você aprendeu a:

• Criar um cliente de chat
• Criar um thread com dois usuários
• Enviar uma mensagem para o thread
• Receber mensagens de um thread
• Remover usuários de um thread

Contribuindo

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.