Guia de início rápido: adicionar bate-papo ao seu aplicativo

Artigo
10/30/2023

Comece a usar os Serviços de Comunicação do Azure usando o SDK de Chat dos Serviços de Comunicação para adicionar bate-papo em tempo real ao seu aplicativo. Neste início rápido, usaremos o SDK de bate-papo para criar threads de bate-papo que permitam que os usuários conversem uns com os outros. Para saber mais sobre os conceitos de bate-papo, visite a documentação conceitual do bate-papo.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Crie um recurso de Serviços de Comunicação.
Instalar a CLI do Azure.
Anote o ponto de extremidade do recurso dos Serviços de Comunicação. Você pode obter o ponto de extremidade no portal do Azure. Como alternativa, você pode encontrar a URL do ponto de extremidade na cadeia de conexão. É o url que vem depois endpoint= e começa com https://.
Um token de acesso de usuário. Certifique-se de definir o escopo para bate-papo e anote a cadeia de caracteres de token, bem como a cadeia de caracteres de user_id. Você também pode usar a CLI do Azure e executar o comando abaixo com sua cadeia de conexão para criar um usuário e um token de acesso.
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
Para obter detalhes, consulte Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configuração

Adicionar a extensão

Adicione a extensão dos Serviços de Comunicação do Azure para a CLI do Azure usando o az extension comando.

az extension add --name communication

Você precisará entrar na CLI do Azure. Você pode entrar executando o az login comando do terminal e fornecendo suas credenciais.

(Opcional) Usar operações de identidade da CLI do Azure sem passar um ponto de extremidade ou token de acesso

Armazene seu endpoint em uma variável de ambiente

Você pode configurar a variável de ambiente para usar operações AZURE_COMMUNICATION_ENDPOINT de chat da CLI do Azure sem precisar usar --endpoint para passar no ponto de extremidade. Para configurar uma variável de ambiente, abra uma janela do console e selecione seu sistema operacional nas guias abaixo. Substitua <yourEndpoint> pelo seu ponto de extremidade real.

Abra uma janela do console e digite o seguinte comando:

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

Depois de adicionar a variável de ambiente, poderá ter de reiniciar todos os programas em execução que irão precisar de ler a variável de ambiente, incluindo a janela da consola. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

Edite o seu .zshrce adicione a variável de ambiente:

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

Depois de adicionar a variável de ambiente, execute source ~/.zshrc a partir da janela da consola para que as alterações entrem em vigor. Se você criou a variável de ambiente com o IDE aberto, talvez seja necessário fechar e reabrir o editor, IDE ou shell para acessar a variável.

Edite o seu .bash_profilee adicione a variável de ambiente:

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

Depois de adicionar a variável de ambiente, execute source ~/.bash_profile a partir da janela da consola para que as alterações entrem em vigor. Se você criou a variável de ambiente com o IDE aberto, talvez seja necessário fechar e reabrir o editor, IDE ou shell para acessar a variável.

Armazene seu token de acesso em uma variável de ambiente

Você pode configurar a variável de ambiente para usar operações AZURE_COMMUNICATION_ACCESS_TOKEN de chat da CLI do Azure sem precisar usar --access-token para passar o token de acesso. Para configurar uma variável de ambiente, abra uma janela do console e selecione seu sistema operacional nas guias abaixo. Substitua <yourAccessToken> pelo seu token de acesso real.

Abra uma janela do console e digite o seguinte comando:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Edite o seu .zshrce adicione a variável de ambiente:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Edite o seu .bash_profilee adicione a variável de ambiente:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Operações

Iniciar um tópico de bate-papo

Use o thread create comando para criar um thread de chat.

az communication chat thread create --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"

Se você tiver armazenado o ponto de extremidade e o token de acesso em variáveis de ambiente, conforme indicado acima, não precisará passá-los para o comando.

az communication chat thread create --topic "<chatTopic>"

Use <chatTopic> para dar um tópico ao tópico. Você pode atualizar o tópico depois que o thread de bate-papo é criado usando o thread update-topic comando.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Atualizar o tópico de um tópico de bate-papo

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"

Substitua <chatThreadId> pelo ID do seu tópico de chat.
Substitua <chatTopic> pelo novo tópico de bate-papo que você deseja definir.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Listar todos os tópicos de bate-papo

O thread list comando retorna a lista de threads de bate-papo de um usuário.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"

Use <startTime> opcionalmente para especificar o primeiro momento para receber mensagens de chat.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Enviar uma mensagem para um tópico de chat

Use o comando para enviar uma mensagem para um thread de bate-papo message send que você criou, identificado por threadId.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"

Substitua <chatThreadId> pelo ID do seu tópico de chat.
Use <content> para fornecer o conteúdo da mensagem de chat.
Use <messageType> para especificar o tipo de conteúdo da mensagem. Os valores possíveis são text e html. Se você não especificar um valor, o padrão será text.
Use <displayName> opcionalmente para especificar o nome de exibição do remetente.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Listar mensagens de bate-papo em um thread de bate-papo

O message list comando retorna a lista de mensagens de bate-papo em um thread de chat.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"

Substitua <chatThreadId> pelo ID do seu tópico de chat.
Use <startTime> opcionalmente para especificar o primeiro momento para receber mensagens de chat.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Receber uma mensagem de chat a partir de um tópico de chat

Você pode recuperar mensagens de bate-papo usando o message list comando.

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"

Substitua <chatThreadId> pelo ID do seu tópico de chat.
Substitua <messageId> pelo ID da mensagem que você deseja recuperar.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Enviar recibo de leitura

Use o message receipt send comando para postar um evento de confirmação de leitura em um thread, em nome de um usuário.

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"

Substitua <chatThreadId> pelo ID do seu tópico de chat.
Substitua <messageId> para especificar o ID da última mensagem lida pelo usuário atual.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Adicionar um usuário como participante ao tópico de bate-papo

Ao criar um thread de bate-papo, você pode adicionar e remover usuários dele. Ao adicionar usuários, você dá a eles acesso para poder enviar mensagens para o thread de bate-papo e adicionar ou remover outros participantes. Antes de chamar o participant add comando, verifique se você adquiriu um novo token de acesso e identidade para esse usuário.

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"

Substitua <chatThreadId> pelo ID do seu tópico de chat.
Substitua <userId> pelo seu userId.
Use <displayName> opcionalmente para especificar o nome de exibição do remetente.
Use <startTime> opcionalmente para especificar o primeiro momento para receber mensagens de chat.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Listar participantes de threads em um thread de bate-papo

Semelhante a adicionar um participante, você também pode listar participantes a partir de um tópico.

Use participant list o comando para recuperar os participantes do thread.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"

Substitua <chatThreadId> pelo ID do seu tópico de chat.
Use <skip> opcionalmente para pular os participantes até uma posição especificada na resposta.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Remover um participante de um tópico de chat

Você pode remover um participante de um bate-papo de um tópico de bate-papo usando o comando 'remover participante'.

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"

Substitua <chatThreadId> pelo ID do seu tópico de chat.
Substitua <userId> pelo userId que você deseja remover do thread de bate-papo.
Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
Substitua <token> pelo token de acesso obtido anteriormente pelo comando em execução identity token issue .

Pré-requisitos

Antes de começar, certifique-se de:

Crie uma conta do Azure com uma assinatura ativa. Para obter detalhes, consulte Criar uma conta gratuitamente.
Instale as versões Node.js Ative LTS e Maintenance LTS.
Criar um recurso do Azure Communication Services. Para obter detalhes, consulte Criar um recurso dos Serviços de Comunicação do Azure. Você precisará registrar seu ponto de extremidade de recurso e a cadeia de conexão para este início rápido.
Crie três Usuários dos Serviços de Comunicação do Azure e emite-lhes um Token de Acesso de Usuário. Certifique-se de definir o escopo para bate-papo e anote a cadeia de caracteres de token, bem como a cadeia de caracteres de user_id. A demonstração completa cria um thread com dois participantes iniciais e, em seguida, adiciona um terceiro participante ao thread. Você também pode usar a CLI do Azure e executar o comando abaixo com sua cadeia de conexão para criar um usuário e um token de acesso.
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
Para obter detalhes, consulte Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configuração

Criar um novo aplicativo Web

Primeiro, abra o terminal ou a janela de comando, crie um novo diretório para seu aplicativo e navegue até ele.

mkdir chat-quickstart && cd chat-quickstart

Execute npm init -y para criar um arquivo package.json com as configurações padrão.

npm init -y

Instalar os pacotes

Use o npm install comando para instalar os SDKs de Serviços de Comunicação para JavaScript abaixo.

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

A --save opção lista a biblioteca como uma dependência no arquivo package.json .

Configurar a estrutura do aplicativo

Este guia de início rápido usa o parcel para agrupar os ativos do aplicativo. Execute o seguinte comando para instalá-lo e listá-lo como uma dependência de desenvolvimento em seu package.json:

npm install parcel --save-dev

Crie um arquivo index.html no diretório raiz do seu projeto. Usaremos esse arquivo como um modelo para adicionar o recurso de bate-papo usando o SDK do Chat de Comunicação do Azure para JavaScript.

<!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>

Crie um arquivo no diretório raiz do seu projeto chamado client.js para conter a lógica do aplicativo para este início rápido.

Criar um cliente de chat

Para criar um cliente de chat em seu aplicativo Web, você usará o ponto de extremidade do Serviço de Comunicações e o token de acesso que foi gerado como parte das etapas de pré-requisito.

Os tokens de acesso de usuário permitem que você crie aplicativos cliente que se autenticam diretamente nos Serviços de Comunicação do Azure. Este início rápido não abrange a criação de uma camada de serviço para gerenciar tokens para seu aplicativo de chat. Consulte conceitos de chat para obter mais informações sobre arquitetura de chat e tokens de acesso de usuário para obter mais informações sobre tokens de acesso.

Dentro do cliente.js use o ponto de extremidade e o token de acesso no código abaixo para adicionar o recurso de bate-papo usando o SDK do Chat de Comunicação do Azure para JavaScript.


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

Substitua endpointUrl pelo ponto de extremidade do recurso Serviços de Comunicação, consulte Criar um recurso dos Serviços de Comunicação do Azure se ainda não tiver feito isso.
Substitua userAccessToken pelo token que você emitiu.

Executar o código

Execute o seguinte comando para executar seu aplicativo:

npx parcel index.html

Abra o navegador e navegue até http://localhost:1234/. No console de ferramentas de desenvolvedor do seu navegador, você verá o seguinte:

Azure Communication Chat client created!

Modelo de objeto

As classes e interfaces a seguir lidam com alguns dos principais recursos do SDK de Chat dos Serviços de Comunicação do Azure para JavaScript.

Name	Description
ChatClient	Esta classe é necessária para a funcionalidade de chat. Você o instancia com suas informações de assinatura e o usa para criar, obter, excluir threads e se inscrever em eventos de bate-papo.
ChatThreadClient	Esta classe é necessária para a funcionalidade Chat Thread. Você obtém uma instância através do ChatClient e usa-a para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter usuários, enviar notificações de digitação e ler confirmações.

Iniciar um tópico de bate-papo

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

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

Use topic para dar um tópico a este bate-papo. Os tópicos podem ser atualizados depois que o tópico de bate-papo é criado usando a UpdateThread função.
Use participants para listar os participantes a serem adicionados ao tópico de bate-papo.

Quando resolvido, createChatThread o método retorna um CreateChatThreadResultarquivo . Este modelo contém uma chatThread propriedade onde você pode acessar o id do thread recém-criado. Em seguida, você pode usar o id para obter uma instância de um ChatThreadClientarquivo . O ChatThreadClient pode então ser usado para executar operações dentro do thread, como enviar mensagens ou listar participantes.

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

Ao atualizar a guia do navegador, você verá o seguinte no console:

Thread created: <thread_id>

Obter um cliente de thread de chat

O getChatThreadClient método retorna um para um chatThreadClient thread que já existe. Ele pode ser usado para executar operações no thread criado: adicionar participantes, enviar mensagem, etc. threadId é o ID exclusivo do thread de chat existente.

let chatThreadClient = chatClient.getChatThreadClient(threadId);
console.log(`Chat Thread client for threadId:${threadId}`);

Adicione este código no lugar do <CREATE CHAT THREAD CLIENT> comentário em client.js, atualize a guia do navegador e verifique o console, você deve ver:

Chat Thread client for threadId: <threadId>

Listar todos os tópicos de bate-papo

O listChatThreads método retorna um PagedAsyncIterableIterator do tipo ChatThreadItem. Ele pode ser usado para listar todos os tópicos de bate-papo. Um iterador de é a resposta retornada de [ChatThreadItem] threads de listagem

const threads = chatClient.listChatThreads();
for await (const thread of threads) {
   // your code here
}

Enviar uma mensagem para um tópico de chat

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

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

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

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

Use senderDisplayName para especificar o nome de exibição do remetente;
Use type para especificar o tipo de mensagem, como 'texto' ou 'html';
Use metadata opcionalmente para incluir quaisquer outros dados que você deseja enviar junto com a mensagem. Este campo fornece um mecanismo para os desenvolvedores estenderem a funcionalidade de mensagens de chat e adicionarem informações personalizadas para o seu caso de uso. Por exemplo, ao compartilhar um link de arquivo na mensagem, talvez você queira adicionar 'hasAttachment: true' nos metadados para que o aplicativo do destinatário possa analisá-lo e exibi-lo adequadamente.

SendChatMessageResult é a resposta retornada do envio de uma mensagem, contém um ID, que é o ID exclusivo da mensagem.

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

Adicione este código no lugar do <SEND MESSAGE TO A CHAT THREAD> comentário em client.js, atualize a guia do navegador e verifique o console.

Message sent!, message id:<number>

Receber mensagens de chat a partir de um tópico de chat

Com a sinalização em tempo real, você pode se inscrever para ouvir novas mensagens recebidas e atualizar as mensagens atuais na memória de acordo. Os Serviços de Comunicação do Azure dão suporte a uma lista de eventos que você pode assinar.

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

Adicione este código no lugar do <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> comentário em client.js. Atualize a guia do navegador, você deve ver no console uma mensagem Notification chatMessageReceived;

Como alternativa, você pode recuperar mensagens de bate-papo pesquisando o listMessages método em intervalos especificados.


const messages = chatThreadClient.listMessages();
for await (const message of messages) {
   // your code here
}

Adicione este código no lugar do <LIST MESSAGES IN A CHAT THREAD> comentário em client.js. Atualize sua guia, no console você deve encontrar a lista de mensagens enviadas neste tópico de bate-papo.

listMessages Retorna diferentes tipos de mensagens que podem ser identificadas pelo chatMessage.type.

Para obter mais detalhes, consulte Tipos de mensagem.

Adicionar um usuário como participante ao tópico de bate-papo

Antes de chamar o addParticipants método, verifique se você adquiriu um novo token de acesso e identidade para esse usuário. O usuário precisará desse token de acesso para inicializar seu cliente de chat.

addParticipantsRequest descreve o objeto de solicitação em participants que lista os participantes a serem adicionados ao thread de chat;

id, obrigatório, é o identificador de comunicação a ser adicionado ao thread de chat.
displayName, opcional, é o nome para exibição do participante do thread.
shareHistoryTime, opcional, é o momento a partir do qual o histórico de bate-papo é compartilhado com o participante. Para compartilhar o histórico desde o início do thread de chat, defina essa propriedade para qualquer data igual ou inferior ao tempo de criação do thread. Para não compartilhar nenhum histórico anterior ao momento em que o participante foi adicionado, defina-o para a data atual. Para partilhar o histórico parcial, defina-o para a data da sua escolha.


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

await chatThreadClient.addParticipants(addParticipantsRequest);

Substitua NEW_PARTICIPANT_USER_ID por um novo ID de usuário Adicione este código no lugar do <ADD NEW PARTICIPANT TO THREAD> comentário no cliente.js

Listar usuários em um tópico de bate-papo

const participants = chatThreadClient.listParticipants();
for await (const participant of participants) {
   // your code here
}

Adicione este código no lugar do comentário em client.js, atualize a guia do <LIST PARTICIPANTS IN A THREAD> navegador e verifique o console, você deve ver informações sobre os usuários em um thread.

Remover usuário de um tópico de bate-papo

Semelhante a adicionar um participante, você pode remover participantes de um tópico de bate-papo. Para remover, terá de controlar os IDs dos participantes que adicionou.

Use removeParticipant o método onde participant é o usuário de comunicação a ser removido do thread.


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

Substitua PARTICIPANT_ID por um ID de usuário usado na etapa anterior (<NEW_PARTICIPANT_USER_ID>). Adicione este código no lugar do <REMOVE PARTICIPANT FROM THREAD> comentário em client.js.

Subscrição de eventos realTimeNotificationConnected e realTimeNotificationDisconnected permite-lhe saber quando a ligação ao servidor de chamadas está ativa.

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

Código de Exemplo

Encontre o código finalizado para este início rápido no GitHub.

Pré-requisitos

Antes de começar, certifique-se de:

Crie uma conta do Azure com uma assinatura ativa. Para obter detalhes, consulte Criar uma conta gratuitamente.
Instale o Python 3.7+.
Criar um recurso do Azure Communication Services. Para obter detalhes, consulte Guia de início rápido: criar e gerenciar recursos dos Serviços de Comunicação. Você precisará registrar seu ponto de extremidade de recurso e a cadeia de conexão para este início rápido.
Um token de acesso de usuário. Certifique-se de definir o escopo para bate-papo e anote a cadeia de caracteres de token, bem como a cadeia de caracteres de user_id. Você também pode usar a CLI do Azure e executar o comando abaixo com sua cadeia de conexão para criar um usuário e um token de acesso.
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
Para obter detalhes, consulte Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configuração

Criar uma aplicação Python nova

Abra o terminal ou a janela de comando, crie um novo diretório para seu aplicativo e vá até ele.

mkdir chat-quickstart && cd chat-quickstart

Use um editor de texto para criar um arquivo chamado start-chat.py no diretório raiz do projeto. Adicione a estrutura para o programa, incluindo o tratamento básico de exceções. Nas seções a seguir, você adicionará todo o código-fonte deste início rápido a este arquivo.

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)

Instalar o SDK

Use o seguinte comando para instalar o SDK:


pip install azure-communication-chat

Modelo de objeto

As classes e interfaces a seguir lidam com alguns dos principais recursos do SDK de Chat dos Serviços de Comunicação do Azure para Python.

Name	Description
`ChatClient`	Esta classe é necessária para a funcionalidade de chat. Você o instancia com suas informações de assinatura e o usa para criar, obter e excluir threads.
`ChatThreadClient`	Esta classe é necessária para a funcionalidade de thread de chat. Você obtém uma instância via `ChatClient`e a usa para enviar, receber, atualizar e excluir mensagens. Você também pode usá-lo para adicionar, remover e obter usuários, além de enviar notificações de digitação e confirmações de leitura.

Criar um cliente de chat

Para criar um cliente de chat, use o ponto de extremidade dos Serviços de Comunicação e o token de acesso gerado como parte das etapas de pré-requisito.

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

Este guia de início rápido não abrange a criação de uma camada de serviço para gerenciar tokens para seu aplicativo de chat, mas isso é recomendado. Para obter mais informações, consulte a seção "Arquitetura de bate-papo" de Conceitos de bate-papo.

Iniciar um tópico de bate-papo

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

Use topic para dar um tópico ao tópico. Você pode atualizar o tópico depois que o thread de bate-papo é criado usando a update_thread função.
Use thread_participants para listar o a ser adicionado ao tópico de bate-papo ChatParticipant . O ChatParticipant toma o CommunicationUserIdentifier tipo como user.

CreateChatThreadResult é o resultado retornado da criação de um thread. Você pode usá-lo para buscar o id tópico de bate-papo que foi criado. Isso id pode ser usado para buscar um ChatThreadClient objeto usando o get_chat_thread_client método. Você pode usar ChatThreadClient para executar outras operações de bate-papo para este tópico de bate-papo.

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)

Obter um cliente de thread de chat

O get_chat_thread_client método retorna um cliente de thread para um thread que já existe. Você pode usá-lo para executar operações no thread criado. Por exemplo, você pode adicionar participantes e enviar mensagens. thread_id é o ID exclusivo do tópico de bate-papo existente.

Você pode usar ChatThreadClient para executar outras operações de bate-papo para este tópico de bate-papo.

thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(thread_id)

Listar todos os tópicos de bate-papo

O list_chat_threads método retorna um iterador do tipo ChatThreadItem.

Use start_time para especificar o primeiro ponto no tempo para obter tópicos de bate-papo.
Use results_per_page para especificar o número máximo de threads de bate-papo retornados por página.

Um iterador de é a resposta retornada dos threads de [ChatThreadItem] listagem.

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)

Enviar uma mensagem para um tópico de chat

Use o método para enviar uma mensagem para um thread de bate-papo send_message que você acabou de criar, identificado por thread_id.

Use content para fornecer o conteúdo da mensagem de chat.
Use chat_message_type para especificar o tipo de conteúdo da mensagem. Os valores possíveis são text e html. Se você não especificar um valor, o padrão será text.
Use sender_display_name para especificar o nome de exibição do remetente.
Use metadata opcionalmente para incluir quaisquer dados adicionais que você deseja enviar junto com a mensagem. Este campo fornece um mecanismo para os desenvolvedores estenderem a funcionalidade de mensagens de chat e adicionarem informações personalizadas para o seu caso de uso. Por exemplo, ao compartilhar um link de arquivo na mensagem, talvez você queira adicionar 'hasAttachment:true' nos metadados para que o aplicativo do destinatário possa analisá-lo e exibi-lo adequadamente.

SendChatMessageResult é a resposta retornada do envio de uma mensagem. Ele contém um ID, que é o ID exclusivo da mensagem.

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)

Receber mensagens de chat a partir de um tópico de chat

Você pode recuperar mensagens de bate-papo sondando o list_messages método em intervalos especificados.

Use results_per_page para especificar o número máximo de mensagens a serem retornadas por página.
Use start_time para especificar o primeiro momento para receber mensagens.

Um iterador de é a resposta retornada das mensagens de [ChatMessage] listagem.

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 Retorna a versão mais recente da mensagem, incluindo quaisquer edições ou exclusões que aconteceram com a mensagem usando update_message e delete_message. Para mensagens excluídas, ChatMessage.deleted_on retorna um datetime valor que indica quando essa mensagem foi excluída. Para mensagens editadas, ChatMessage.edited_on retorna um datetime valor que indica quando a mensagem foi editada. Você pode acessar a hora original de criação da mensagem usando ChatMessage.created_on, que pode ser usado para ordenar as mensagens.

list_messages Retorna diferentes tipos de mensagens, que podem ser identificadas pelo ChatMessage.type.

Para obter mais informações, consulte Tipos de mensagem.

Enviar recibo de leitura

Você usa o send_read_receipt método para postar um evento de confirmação de leitura em um thread, em nome de um usuário.

Use message_id para especificar o ID da última mensagem lida pelo usuário atual.

content='hello world'

send_message_result = chat_thread_client.send_message(content)
chat_thread_client.send_read_receipt(message_id=send_message_result.id)

Adicionar um usuário como participante ao tópico de bate-papo

Ao criar um thread de bate-papo, você pode adicionar e remover usuários dele. Ao adicionar usuários, você dá a eles acesso para poder enviar mensagens para o thread de bate-papo e adicionar ou remover outros participantes. Antes de chamar o add_participants método, verifique se você adquiriu um novo token de acesso e identidade para esse usuário. O usuário precisa desse token de acesso para inicializar o cliente de chat.

Você pode adicionar um ou mais usuários ao thread de bate-papo usando o add_participants método, desde que um novo token de acesso e identidade estejam disponíveis para todos os usuários.

A list(tuple(ChatParticipant, CommunicationError)) é devolvido. Quando o participante é adicionado com sucesso, espera-se uma lista vazia. Se você encontrar um erro ao adicionar um participante, a lista será preenchida com os participantes com falha, juntamente com o erro encontrado.

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)

Listar participantes de threads em um thread de bate-papo

Semelhante a adicionar um participante, você também pode listar participantes a partir de um tópico.

Use list_participants para recuperar os participantes do thread. Ambos os comandos a seguir são opcionais:

Use results_per_page para especificar o número máximo de participantes a serem retornados por página.
Use skip para ignorar os participantes até uma posição especificada na resposta.

Um iterador de [ChatParticipant] é a resposta retornada dos participantes da lista.

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)

Executar o código

Execute o aplicativo a partir do diretório do aplicativo com o python comando.

python start-chat.py

Código de Exemplo

Encontre o código finalizado para este início rápido no GitHub.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Java Development Kit (JDK) versão 8 ou superior.
Apache Maven.
Criar um recurso do Azure Communication Services. Para obter detalhes, consulte Criar um recurso dos Serviços de Comunicação do Azure. Você precisará registrar seu ponto de extremidade de recurso e a cadeia de conexão para este início rápido.
Um token de acesso de usuário. Certifique-se de definir o escopo para bate-papo e anote a cadeia de caracteres de token, bem como a cadeia de caracteres de user_id. Você também pode usar a CLI do Azure e executar o comando abaixo com sua cadeia de conexão para criar um usuário e um token de acesso.
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
Para obter detalhes, consulte Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configuração

Criar uma nova aplicação Java

Abra seu terminal ou janela de comando e navegue até o diretório onde você gostaria de criar sua aplicação Java. Execute o comando abaixo para gerar o projeto Java a partir do modelo maven-archetype-quickstart.

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Você notará que o objetivo 'generate' criou um diretório com o mesmo nome do artifactId. Sob este diretório, o contém o código-fonte do projeto, o diretório contém a fonte de teste e o arquivo pom.xml é o src/main/java directorysrc/test/java Project Object Model ou POM.

Atualize o arquivo POM do seu aplicativo para usar Java 8 ou superior:

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

Adicionar as referências de pacote para o SDK de bate-papo

No seu arquivo POM, faça referência ao azure-communication-chat pacote com as APIs de bate-papo:

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

Para autenticação, seu cliente precisa fazer referência ao azure-communication-common pacote:

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

Modelo de objeto

As classes e interfaces a seguir lidam com alguns dos principais recursos do SDK de Chat dos Serviços de Comunicação do Azure para Java.

Name	Description
ChatClient	Esta classe é necessária para a funcionalidade de chat. Você o instancia com suas informações de assinatura e o usa para criar, obter e excluir threads.
ChatAsyncClient	Essa classe é necessária para a funcionalidade de bate-papo assíncrono. Você o instancia com suas informações de assinatura e o usa para criar, obter e excluir threads.
ChatThreadClient	Esta classe é necessária para a funcionalidade Chat Thread. Você obtém uma instância através do ChatClient e usa-a para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter usuários, enviar notificações de digitação e ler confirmações.
ChatThreadAsyncClient	Essa classe é necessária para a funcionalidade de thread de bate-papo assíncrono. Você obtém uma instância por meio do ChatAsyncClient e a usa para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter usuários, enviar notificações de digitação e ler confirmações.

Criar um cliente de chat

Para criar um cliente de chat, você usará o ponto de extremidade do Serviço de Comunicações e o token de acesso que foi gerado como parte das etapas de pré-requisito. Os tokens de acesso de usuário permitem que você crie aplicativos cliente que se autenticam diretamente nos Serviços de Comunicação do Azure. Depois de gerar esses tokens em seu servidor, passe-os de volta para um dispositivo cliente. Você precisa usar a classe CommunicationTokenCredential do Common SDK para passar o token para seu cliente de chat.

Saiba mais sobre a arquitetura de bate-papo

Ao adicionar as instruções de importação, certifique-se de adicionar apenas importações dos namespaces com.azure.communication.chat e com.azure.communication.chat.models, e não do namespace com.azure.communication.chat.implementation. No arquivo App.java que foi gerado via Maven, você pode usar o seguinte código para começar:

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

Iniciar um tópico de bate-papo

Use o createChatThread método para criar um thread de chat. createChatThreadOptions é usado para descrever a solicitação de thread.

Use o topic parâmetro do construtor para dar um tópico a este chat; O tópico pode ser atualizado depois que o tópico de bate-papo é criado usando a UpdateThread função.
Use participants para listar os participantes do thread a serem adicionados ao thread. ChatParticipantleva o usuário criado no início rápido do Token de Acesso do Usuário.

CreateChatThreadResult é a resposta retornada da criação de um thread de chat. Ele contém um getChatThread() método, que retorna o objeto que pode ser usado para obter o cliente de thread a partir do qual você pode obter o ChatThreadChatThreadClient para executar operações no thread criado: adicionar participantes, enviar mensagem, etc. O ChatThread objeto também contém o getId() método, que recupera a ID exclusiva do thread.

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

Listar tópicos de bate-papo

Use o método para recuperar uma lista de threads de bate-papo listChatThreads existentes.

PagedIterable<ChatThreadItem> chatThreads = chatClient.listChatThreads();

chatThreads.forEach(chatThread -> {
    System.out.printf("ChatThread id is %s.\n", chatThread.getId());
});

Obter um cliente de thread de chat

O getChatThreadClient método retorna um cliente de thread para um thread que já existe. Ele pode ser usado para executar operações no thread criado: adicionar participantes, enviar mensagem, etc. chatThreadId é o ID exclusivo do tópico de bate-papo existente.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Enviar uma mensagem para um tópico de chat

Use o método para enviar uma mensagem para o sendMessage thread que você criou, identificado por chatThreadId. sendChatMessageOptions é usado para descrever a solicitação de mensagem de chat.

Use content para fornecer o conteúdo da mensagem de chat.
Use type para especificar o tipo de conteúdo da mensagem de chat, TEXT ou HTML.
Use senderDisplayName para especificar o nome de exibição do remetente.
Use metadata opcionalmente para incluir quaisquer dados adicionais que você deseja enviar junto com a mensagem. Este campo fornece um mecanismo para os desenvolvedores estenderem a funcionalidade de mensagens de chat e adicionarem informações personalizadas para o seu caso de uso. Por exemplo, ao compartilhar um link de arquivo na mensagem, talvez você queira adicionar hasAttachment:true metadados para que o aplicativo do destinatário possa analisá-los e exibi-los adequadamente.

A resposta sendChatMessageResult contém um id, que é o ID exclusivo da mensagem.

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

Receber mensagens de chat a partir de um tópico de chat

Você pode recuperar mensagens de bate-papo sondando o listMessages método no cliente de thread de bate-papo em intervalos especificados.

chatThreadClient.listMessages().forEach(message -> {
    System.out.printf("Message id is %s.\n", message.getId());
});

listMessages Retorna a versão mais recente da mensagem, incluindo quaisquer edições ou exclusões que aconteceram com a mensagem usando .editMessage() e .deleteMessage(). Para mensagens excluídas, chatMessage.getDeletedOn() retorna um valor datetime que indica quando essa mensagem foi excluída. Para mensagens editadas, chatMessage.getEditedOn() retorna uma data/hora indicando quando a mensagem foi editada. A hora original de criação da mensagem pode ser acessada usando chatMessage.getCreatedOn()o , e pode ser usada para ordenar as mensagens.

Leia mais sobre os tipos de mensagem aqui: Tipos de mensagem.

Enviar recibo de leitura

Use o método para postar um evento de confirmação de leitura em um thread de bate-papo sendReadReceipt , em nome de um usuário. chatMessageId é o ID exclusivo da mensagem de chat que foi lida.

String chatMessageId = message.getId();
chatThreadClient.sendReadReceipt(chatMessageId);

Listar participantes do bate-papo

Use listParticipants para recuperar uma coleção paginada contendo os participantes do thread de bate-papo identificados por chatThreadId.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.forEach(chatParticipant -> {
    System.out.printf("Participant id is %s.\n", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId());
});

Adicionar um usuário como participante ao tópico de bate-papo

Depois que um thread de bate-papo é criado, você pode adicionar e remover usuários dele. Ao adicionar usuários, você dá a eles acesso para enviar mensagens para o histórico de bate-papo e adicionar/remover outros participantes. Você precisará começar obtendo um novo token de acesso e identidade para esse usuário. Antes de chamar o método addParticipants, verifique se você adquiriu um novo token de acesso e identidade para esse usuário. O usuário precisará desse token de acesso para inicializar seu cliente de chat.

Use o addParticipants método para adicionar participantes ao thread.

communicationIdentifier, required, é o CommunicationIdentifier que você criou pelo CommunicationIdentityClient no início rápido do Token de Acesso do Usuário.
displayName, opcional, é o nome para exibição do participante do thread.
shareHistoryTime, opcional, é o momento a partir do qual o histórico de bate-papo é compartilhado com o participante. Para compartilhar o histórico desde o início do thread de chat, defina essa propriedade para qualquer data igual ou inferior ao tempo de criação do thread. Para não compartilhar nenhum histórico anterior ao momento em que o participante foi adicionado, defina-o para a data atual. Para compartilhar o histórico parcial, defina-o para a data desejada.

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

Executar o código

Navegue até o diretório que contém o arquivo pom.xml e compile o projeto usando o seguinte mvn comando.

mvn compile

Em seguida, compile o pacote.

mvn package

Execute o seguinte mvn comando para executar o aplicativo.

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

Código de Exemplo

Encontre o código finalizado para este início rápido no GitHub.

Pré-requisitos

Antes de começar, certifique-se de:

Crie uma conta do Azure com uma assinatura ativa. Para obter detalhes, consulte Criar uma conta gratuitamente.
Instale o Android Studio, estaremos usando o Android Studio para criar um aplicativo Android para o início rápido para instalar dependências.
Criar um recurso do Azure Communication Services. Para obter detalhes, consulte Criar um recurso dos Serviços de Comunicação do Azure. Você precisará registrar seu ponto de extremidade de recurso e a cadeia de conexão para este início rápido.
Crie dois Usuários de Serviços de Comunicação e emite-lhes um Token de Acesso de Usuário. Certifique-se de definir o escopo para bate-papo e anote a cadeia de caracteres de token e a cadeia de caracteres de user_id. Neste início rápido, criaremos um thread com um participante inicial e, em seguida, adicionaremos um segundo participante ao thread. Você também pode usar a CLI do Azure e executar o comando abaixo com sua cadeia de conexão para criar um usuário e um token de acesso.
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
Para obter detalhes, consulte Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configuração

Criar uma nova aplicação Android

Abra o Android Studio e selecione Create a new project.
Na janela seguinte, selecione Empty Activity como o modelo de projeto.
Ao escolher opções, insira ChatQuickstart como o nome do projeto.
Clique em Avançar e escolha o diretório onde deseja que o projeto seja criado.

Instalar as bibliotecas

Usaremos o Gradle para instalar as dependências necessárias dos Serviços de Comunicação. Na linha de comando, navegue dentro do diretório raiz do ChatQuickstart projeto. Abra o arquivo build.gradle do aplicativo e adicione as seguintes dependências ao ChatQuickstart destino:

implementation 'com.azure.android:azure-communication-common:' + $azureCommunicationCommonVersion
implementation 'com.azure.android:azure-communication-chat:' + $azureCommunicationChatVersion
implementation 'org.slf4j:slf4j-log4j12:1.7.29'

Consulte https://search.maven.org/artifact/com.azure.android/azure-communication-common e https://search.maven.org/artifact/com.azure.android/azure-communication-chat para obter os números de versão mais recentes.

Excluir metaarquivos em opções de empacotamento no root 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")
    }
}

(Alternativa) Para instalar bibliotecas através do Maven

Para importar a biblioteca para seu projeto usando o sistema de compilação Maven, adicione-a à seção do arquivo do seu aplicativopom.xml, especificando sua ID de artefato e a dependencies versão que você deseja usar:

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

Configurar uma Função do Azure

Consulte a integração do Azure Function para obter detalhes. É altamente recomendável integrar com o Azure Function para evitar a codificação de parâmetros de aplicativos.

Configure constantes de aplicativo:

Crie uma classe ApplicationConstants que armazene todas as constantes do aplicativo:

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

Configurar os espaços reservados

Abra e edite o ficheiro MainActivity.java. Neste início rápido, adicionaremos nosso código ao MainActivitye visualizaremos a saída no console. Este início rápido não aborda a criação de uma interface do usuário. Na parte superior do arquivo, importe o , Azure Communication Chate outras bibliotecas do Azure Communication Commonsistema:

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;

Copie o seguinte código para a classe MainActivity no arquivo MainActivity.java:

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

Inicializar parâmetros do aplicativo

Nota

A inicialização ApplicationConstants precisa ser adicionada se MainActivity.java UMA das seguintes condições for atendida: 1. O recurso de notificação por push NÃO está habilitado. 2. A versão da biblioteca do Chat de Comunicação do Azure para Android é < '2.0.0'. Caso contrário, consulte a etapa 11 em Notificações push do Android. Consulte o exemplo de APP da versão do SDK que você está consumindo para referência.

ACS_ENDPOINTFIRST_USER_ACCESS_TOKEN e FIRST_USER_ID são retornados de chamar a Função do Azure. Consulte a integração do Azure Function para obter detalhes. Usamos a resposta de chamar o Azure Function para inicializar a lista de parâmetros:

ACS_ENDPOINT: o ponto de extremidade do seu recurso de Serviços de Comunicação.
FIRST_USER_ID e SECOND_USER_ID: IDs de usuário válidos dos Serviços de Comunicação gerados pelo recurso dos Serviços de Comunicação.
FIRST_USER_ACCESS_TOKEN: o token de acesso dos Serviços de Comunicação para <FIRST_USER_ID>.

Bloco de código para inicializar parâmetros de aplicativo chamando a Função do 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);
    }

Criar um cliente de chat

Substitua o comentário <CREATE A CHAT CLIENT> pelo seguinte código (coloque as instruções de importação na parte superior do arquivo):

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

Modelo de objeto

As classes e interfaces a seguir lidam com alguns dos principais recursos do SDK de Chat dos Serviços de Comunicação do Azure para JavaScript.

Name	Description
ChatClient/ChatAsyncClient	Esta classe é necessária para a funcionalidade de chat. Você o instancia com suas informações de assinatura e o usa para criar, obter, excluir threads e se inscrever em eventos de bate-papo.
ChatThreadClient/ChatThreadAsyncClient	Esta classe é necessária para a funcionalidade Chat Thread. Você obtém uma instância através do ChatClient e usa-a para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter usuários, enviar notificações de digitação e ler confirmações.

Iniciar um tópico de bate-papo

Usaremos o nosso ChatAsyncClient para criar um novo thread com um usuário inicial.

Substitua o comentário <CREATE A CHAT THREAD> pelo código seguinte:

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

Obter um cliente de thread de chat

Agora que criamos um thread de bate-papo, obteremos um ChatThreadAsyncClient para executar operações dentro do thread. Substitua o comentário <CREATE A CHAT THREAD CLIENT> pelo código seguinte:

ChatThreadAsyncClient chatThreadAsyncClient = new ChatThreadClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .chatThreadId(threadId)
    .buildAsyncClient();

Enviar uma mensagem para um tópico de chat

Vamos enviar mensagem para esse tópico agora.

Substitua o comentário <SEND A MESSAGE> pelo código seguinte:

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

Receber mensagens de chat a partir de um tópico de chat

Notificações em tempo real

Com a sinalização em tempo real, você pode assinar novas mensagens recebidas e atualizar as mensagens atuais na memória de acordo. Os Serviços de Comunicação do Azure dão suporte a uma lista de eventos que você pode assinar.

Substitua o comentário <RECEIVE CHAT MESSAGES> pelo seguinte código (coloque as instruções de importação na parte superior do arquivo):


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

Importante

Problema conhecido: ao usar o Android Chat e o Calling SDK juntos no mesmo aplicativo, o recurso de notificações em tempo real do Chat SDK não funciona. Você pode obter um problema de resolução de dependência. Enquanto estamos trabalhando em uma solução, você pode desativar o recurso de notificações em tempo real adicionando as seguintes informações de dependência no arquivo build.gradle do aplicativo e, em vez disso, pesquisar a API GetMessages para exibir mensagens de entrada para os usuários.

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'

Observe com a atualização acima, se o aplicativo tentar tocar em qualquer uma das APIs de notificação como chatAsyncClient.startRealtimeNotifications() ou chatAsyncClient.addEventHandler(), haverá um erro de tempo de execução.

Notificações push

Por favor, verifique as notificações push do Android para obter detalhes.

Adicionar um usuário como participante ao tópico de bate-papo

Substitua o comentário <ADD A USER> pelo código seguinte:

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

Listar usuários em um thread

Substitua o <LIST USERS> comentário pelo seguinte código (coloque as instruções de importação na parte superior do arquivo):

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

Remover usuário de um tópico de bate-papo

Vamos remover o segundo usuário do thread agora.

Substitua o comentário <REMOVE A USER> pelo código seguinte:

// Using the unique ID of the participant.
chatThreadAsyncClient.removeParticipant(new CommunicationUserIdentifier(secondUserId)).get();

Enviar uma notificação de digitação

Substitua o comentário <SEND A TYPING NOTIFICATION> pelo código seguinte:

chatThreadAsyncClient.sendTypingNotification().get();

Enviar um recibo de leitura

Enviaremos o recibo de leitura da mensagem enviada acima.

Substitua o comentário <SEND A READ RECEIPT> pelo código seguinte:

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Listar confirmações de leitura

Substitua o comentário <READ RECEIPTS> pelo código seguinte:

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

Executar o código

No Android Studio, pressione o botão Executar para criar e executar o projeto. No console, você pode visualizar a saída do código e a saída do registrador do ChatClient.

Código de Exemplo

Encontre o código finalizado para este início rápido no GitHub.

Pré-requisitos

Antes de começar, certifique-se de:

Crie uma conta do Azure com uma assinatura ativa. Para obter detalhes, consulte Criar uma conta gratuitamente.
Instalar o Visual Studio
Criar um recurso do Azure Communication Services. Para obter detalhes, consulte Criar um recurso dos Serviços de Comunicação do Azure. Você precisará registrar seu ponto de extremidade de recurso e a cadeia de conexão para este início rápido.
Um token de acesso de usuário. Certifique-se de definir o escopo para bate-papo e anote a cadeia de caracteres de token, bem como a cadeia de caracteres de user_id. Você também pode usar a CLI do Azure e executar o comando abaixo com sua cadeia de conexão para criar um usuário e um token de acesso.
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
Para obter detalhes, consulte Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configuração

Criar um novo aplicativo C#

Em uma janela de console (como cmd, PowerShell ou Bash), use o comando para criar um novo aplicativo de console com o dotnet new nome ChatQuickstart. Este comando cria um projeto C# "Hello World" simples com um único arquivo de origem: Program.cs.

dotnet new console -o ChatQuickstart

Altere seu diretório para a pasta do aplicativo recém-criada e use o dotnet build comando para compilar seu aplicativo.

cd ChatQuickstart
dotnet build

Instalar o pacote

Instalar o SDK do Chat de Comunicação do Azure para .NET

dotnet add package Azure.Communication.Chat

Modelo de objeto

As classes a seguir lidam com alguns dos principais recursos do SDK de Chat dos Serviços de Comunicação do Azure para C#.

Name	Description
ChatClient	Esta classe é necessária para a funcionalidade de chat. Você o instancia com suas informações de assinatura e o usa para criar, obter e excluir threads.
ChatThreadClient	Esta classe é necessária para a funcionalidade Chat Thread. Você obtém uma instância por meio do ChatClient e a usa para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter participantes, enviar notificações de digitação e ler confirmações.

Criar um cliente de chat

Para criar um cliente de chat, você usará seu ponto de extremidade dos Serviços de Comunicação e o token de acesso que foi gerado como parte das etapas de pré-requisito. Você precisa usar a CommunicationIdentityClient classe do SDK de identidade para criar um usuário e emitir um token para passar para seu cliente de chat.

Saiba mais sobre os Tokens de Acesso de Usuário.

Este início rápido não abrange a criação de uma camada de serviço para gerenciar tokens para seu aplicativo de chat, embora seja recomendado. Saiba mais sobre a arquitetura de bate-papo

Copie os seguintes trechos de código e cole no arquivo de origem: Programa.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);
        }
    }
}

Iniciar um tópico de bate-papo

Use o createChatThread método no chatClient para criar um thread de chat

Use topic para dar um tópico a este bate-papo; O tópico pode ser atualizado depois que o tópico de bate-papo é criado usando a UpdateTopic função.
Use participants a propriedade para passar uma lista de objetos a serem adicionados ao thread de ChatParticipant chat. O ChatParticipant objeto é inicializado com um CommunicationIdentifier objeto. CommunicationIdentifier pode ser do tipo CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier ou PhoneNumberIdentifier. Por exemplo, para obter um objeto, você precisará passar uma ID de acesso que você criou seguindo as instruções para Criar um CommunicationIdentifier usuário

O objeto de resposta do createChatThread método contém os chatThread detalhes. Para interagir com as operações do thread de chat, como adicionar participantes, enviar uma mensagem, excluir uma mensagem, etc., uma chatThreadClient instância do cliente precisa ser instanciada usando o GetChatThreadClient método no ChatClient cliente.

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;

Obter um cliente de thread de chat

O GetChatThreadClient método retorna um cliente de thread para um thread que já existe. Ele pode ser usado para executar operações no thread criado: adicionar membros, enviar mensagem, etc. threadId é o ID exclusivo do thread de chat existente.

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Listar todos os tópicos de bate-papo

Use GetChatThreads para recuperar todos os tópicos de bate-papo dos quais o usuário faz parte.

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

Enviar uma mensagem para um tópico de chat

Use SendMessage para enviar uma mensagem para um thread.

Use content para fornecer o conteúdo da mensagem, é necessário.
Use type para o tipo de conteúdo da mensagem, como 'Texto' ou 'Html'. Se não for especificado, 'Texto' será definido.
Use senderDisplayName para especificar o nome de exibição do remetente. Se não for especificado, a cadeia de caracteres vazia será definida.
Use metadata opcionalmente para incluir quaisquer dados adicionais que você deseja enviar junto com a mensagem. Este campo fornece um mecanismo para os desenvolvedores estenderem a funcionalidade de mensagens de chat e adicionarem informações personalizadas para o seu caso de uso. Por exemplo, ao compartilhar um link de arquivo na mensagem, talvez você queira adicionar 'hasAttachment:true' nos metadados para que o aplicativo do destinatário possa analisá-lo e exibi-lo adequadamente.

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;

Receber mensagens de chat a partir de um tópico de chat

Você pode recuperar mensagens de bate-papo sondando o GetMessages método no cliente de thread de bate-papo em intervalos especificados.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

GetMessages usa um parâmetro opcional DateTimeOffset . Se esse deslocamento for especificado, você receberá mensagens que foram recebidas, atualizadas ou excluídas depois dele. Observe que as mensagens recebidas antes do tempo de deslocamento, mas editadas ou removidas depois dele, também serão retornadas.

GetMessages Retorna a versão mais recente da mensagem, incluindo quaisquer edições ou exclusões que aconteceram com a mensagem usando UpdateMessage e DeleteMessage. Para mensagens excluídas, chatMessage.DeletedOn retorna um valor datetime que indica quando essa mensagem foi excluída. Para mensagens editadas, chatMessage.EditedOn retorna uma data/hora indicando quando a mensagem foi editada. A hora original de criação da mensagem pode ser acessada usando chatMessage.CreatedOno , e pode ser usada para ordenar as mensagens.

GetMessages Devolve diferentes tipos de mensagens que podem ser identificadas por chatMessage.Type. Estes tipos são:

Text: Mensagem de chat normal enviada por um membro do tópico.
Html: Uma mensagem de texto formatada. Observe que os usuários dos Serviços de Comunicação atualmente não podem enviar mensagens RichText. Esse tipo de mensagem é suportado por mensagens enviadas de usuários do Teams para usuários do Serviços de Comunicação em cenários de interoperabilidade do Teams.
TopicUpdated: Mensagem do sistema que indica que o tópico foi atualizado. (somente leitura)
ParticipantAdded: Mensagem do sistema que indica que um ou mais participantes foram adicionados ao tópico de chat. (somente leitura)
ParticipantRemoved: Mensagem do sistema que indica que um participante foi removido do tópico de chat.

Para obter mais detalhes, consulte Tipos de mensagem.

Adicionar um usuário como participante ao tópico de bate-papo

Depois que um thread é criado, você pode adicionar e remover usuários dele. Ao adicionar usuários, você dá a eles acesso para poder enviar mensagens para o thread e adicionar/remover outro participante. Antes de ligar AddParticipants, verifique se você adquiriu um novo token de acesso e identidade para esse usuário. O usuário precisará desse token de acesso para inicializar seu cliente de chat.

Use AddParticipants para adicionar um ou mais participantes ao tópico de bate-papo. A seguir estão os atributos suportados para cada participante do thread:

communicationUser, obrigatório, é a identidade do participante do thread.
displayName, opcional, é o nome para exibição do participante do thread.
shareHistoryTime, opcional, hora a partir da qual o histórico do chat é partilhado com o participante.

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

Obter participantes do tópico

Use GetParticipants para recuperar os participantes do tópico de bate-papo.

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

Enviar recibo de leitura

Use SendReadReceipt para notificar outros participantes de que a mensagem é lida pelo usuário.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Executar o código

Execute o aplicativo a partir do diretório do aplicativo com o dotnet run comando.

dotnet run

Código de Exemplo

Encontre o código finalizado para este início rápido no GitHub.

Pré-requisitos

Antes de começar, certifique-se de:

Crie uma conta do Azure com uma assinatura ativa. Para obter detalhes, consulte Criar uma conta gratuitamente.
Instale Xcode e CocoaPods. Você usa o Xcode para criar um aplicativo iOS para o início rápido e o CocoaPods para instalar dependências.
Criar um recurso do Azure Communication Services. Para obter detalhes, consulte Guia de início rápido: criar e gerenciar recursos dos Serviços de Comunicação. Você precisará registrar seu ponto de extremidade de recurso e a cadeia de conexão para este início rápido.
Crie dois usuários nos Serviços de Comunicação do Azure e emite-lhes um Token de Acesso de Usuário. Certifique-se de definir o escopo para bate-papo e anote a cadeia de caracteres de token, bem como a cadeia de caracteres de user_id. Neste início rápido, você cria um thread com um participante inicial e, em seguida, adiciona um segundo participante ao thread. Você também pode usar a CLI do Azure e executar o comando abaixo com sua cadeia de conexão para criar um usuário e um token de acesso.
```
az communication identity token issue --scope chat --connection-string "yourConnectionString"
```
Para obter detalhes, consulte Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configuração

Criar uma nova aplicação iOS

Abra o Xcode e selecione Criar um novo projeto Xcode. Em seguida, selecione iOS como a plataforma e App para o modelo.

Para o nome do projeto, digite ChatQuickstart. Em seguida, selecione Storyboard como interface, UIKit App Delegate como o ciclo de vida e Swift como o idioma.

Selecione Avançar e escolha o diretório onde deseja que o projeto seja criado.

Instalar as bibliotecas

Use o CocoaPods para instalar as dependências necessárias dos Serviços de Comunicação.

Na linha de comando, vá para dentro do diretório raiz do ChatQuickstart projeto iOS. Crie um Podfile com o seguinte comando: pod init.

Abra o Podfile e adicione as seguintes dependências ao ChatQuickstart destino:

pod 'AzureCommunicationChat', '~> 1.3.4'

Instale as dependências com o seguinte comando: pod install. Observe que isso também cria um espaço de trabalho Xcode.

Depois de executar pod install, reabra o projeto no Xcode selecionando o recém-criado .xcworkspace.

Configurar os espaços reservados

Abra o espaço de trabalho ChatQuickstart.xcworkspace no Xcode e, em seguida, abra ViewController.swifto .

Neste início rápido, você adiciona seu código ao viewControllere visualiza a saída no console do Xcode. Este início rápido não aborda a criação de uma interface de usuário no iOS.

Na parte superior do viewController.swift, importe as AzureCommunication e AzureCommunicatonChat bibliotecas:

import AzureCommunicationCommon
import AzureCommunicationChat

Copie o seguinte código para o viewDidLoad() método de ViewController:

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

Para fins de demonstração, usaremos um semáforo para sincronizar seu código. Nas etapas a seguir, você substitui os espaços reservados por código de exemplo usando a biblioteca de Chat dos Serviços de Comunicação do Azure.

Criar um cliente de chat

Para criar um cliente de chat, você usará seu ponto de extremidade dos Serviços de Comunicação e o token de acesso que foi gerado como parte das etapas de pré-requisito.

Saiba mais sobre os Tokens de Acesso de Usuário.

Este início rápido não abrange a criação de uma camada de serviço para gerenciar tokens para seu aplicativo de chat, embora seja recomendado. Saiba mais sobre a arquitetura de bate-papo

Substitua o comentário <CREATE A CHAT CLIENT> pelo trecho de código abaixo:

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
)

Substitua <ACS_RESOURCE_ENDPOINT> pelo ponto de extremidade do seu recurso dos Serviços de Comunicação do Azure. Substitua <ACCESS_TOKEN> por um token de acesso válido dos Serviços de Comunicação.

Modelo de objeto

As classes e interfaces a seguir lidam com alguns dos principais recursos do SDK de Chat dos Serviços de Comunicação do Azure para iOS.

Name	Description
`ChatClient`	Esta classe é necessária para a funcionalidade de chat. Você o instancia com suas informações de assinatura e o usa para criar, obter, excluir threads e se inscrever em eventos de bate-papo.
`ChatThreadClient`	Esta classe é necessária para a funcionalidade de thread de chat. Você obtém uma instância via `ChatClient`e a usa para enviar, receber, atualizar e excluir mensagens. Você também pode usá-lo para adicionar, remover e obter usuários, enviar notificações de digitação e ler confirmações.

Iniciar um tópico de bate-papo

CreateChatThreadResult é a resposta retornada da criação de um thread de chat. Ele contém uma chatThread propriedade que é o ChatThreadProperties objeto. Este objeto contém o threadId que pode ser usado para obter um ChatThreadClient para executar operações no thread criado: adicionar participantes, enviar mensagem, etc.

Substitua o comentário <CREATE A CHAT THREAD> pelo trecho de código abaixo:

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

Substitua <USER_ID> por um ID de usuário válido dos Serviços de Comunicação.

Você está usando um semáforo aqui para aguardar o manipulador de conclusão antes de continuar. Em etapas posteriores, você usará o da resposta retornada para o threadId manipulador de conclusão.

Listar todos os tópicos de bate-papo

Depois de criar um thread de chat, podemos listar todos os threads de chat chamando o listChatThreads método em ChatClient. Substitua o comentário <LIST ALL CHAT THREADS> pelo código seguinte:

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

Obter um cliente de thread de chat

O createClient método retorna um para um ChatThreadClient thread que já existe. Ele pode ser usado para executar operações no thread criado: adicionar participantes, enviar mensagem, etc. threadId é o ID exclusivo do thread de chat existente.

Substitua o comentário <GET A CHAT THREAD CLIENT> pelo código seguinte:

let chatThreadClient = try chatClient.createClient(forThread: threadId!)

Enviar uma mensagem para um tópico de chat

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

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

Use content para fornecer o conteúdo da mensagem de bate-papo
Use senderDisplayName para especificar o nome de exibição do remetente
Use type para especificar o tipo de mensagem, como 'texto' ou 'html'
Use metadata opcionalmente para incluir quaisquer dados adicionais que você deseja enviar junto com a mensagem. Este campo fornece um mecanismo para os desenvolvedores estenderem a funcionalidade de mensagens de chat e adicionarem informações personalizadas para o seu caso de uso. Por exemplo, ao compartilhar um link de arquivo na mensagem, talvez você queira adicionar 'hasAttachment:true' nos metadados para que o aplicativo do destinatário possa analisá-lo e exibi-lo adequadamente.

SendChatMessageResult é a resposta retornada do envio de uma mensagem, contém um ID, que é o ID exclusivo da mensagem.

Substitua o comentário <SEND A MESSAGE> pelo trecho de código abaixo:

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

Enviar um recibo de leitura

Use o método para postar um evento de confirmação de leitura em um thread de bate-papo sendReadReceipt , em nome de um usuário. messageId é o ID exclusivo da mensagem de chat que foi lida.

Substitua o comentário <SEND A READ RECEIPT> pelo código abaixo:

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

Receber mensagens de chat a partir de um tópico de chat

Substitua o comentário <RECEIVE MESSAGES> pelo código abaixo. Depois de ativar as notificações, tente enviar novas mensagens para ver o 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
    }
})

Como alternativa, você pode recuperar mensagens de bate-papo pesquisando o listMessages método em intervalos especificados. Consulte o seguinte trecho de código para 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()

Adicionar um usuário como participante ao tópico de bate-papo

Depois que um thread é criado, você pode adicionar e remover usuários dele. Ao adicionar usuários, você dá a eles acesso para poder enviar mensagens para o thread e adicionar/remover outro participante. Antes de ligar add, verifique se você adquiriu um novo token de acesso e identidade para esse usuário. O usuário precisará desse token de acesso para inicializar seu cliente de chat.

Use o add método de para adicionar um ou mais participantes ao tópico de ChatThreadClient bate-papo. A seguir estão os atributos suportados para cada participante do thread:

id, obrigatório, é a identidade do participante do thread.
displayName, opcional, é o nome para exibição do participante do thread.
shareHistoryTime, opcional, hora a partir da qual o histórico do chat é partilhado com o participante.

Substitua o comentário <ADD A USER> pelo código seguinte:

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

Substitua <USER_ID> pelo ID de usuário dos Serviços de Comunicação do usuário a ser adicionado.

Listar usuários em um thread

Use o método para obter todos os participantes para um tópico de bate-papo listParticipants específico.

Substitua o comentário <LIST USERS> pelo código seguinte:

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

Notificações push

As notificações por push notificam os clientes sobre mensagens recebidas em um thread de bate-papo em situações em que o aplicativo móvel não está sendo executado em primeiro plano. Atualmente, o envio de notificações por push de chat com o Hub de Notificação é compatível com o IOS SDK na versão 1.3.0. Consulte o artigo Ativar notificação por push em seu aplicativo de bate-papo para obter detalhes.

Executar o código

No Xcode, pressione o botão Executar para criar e executar o projeto. No console você pode visualizar a saída do código e a saída do logger do ChatClient.

Nota: Defina Build Settings > Build Options > Enable Bitcode como No. Atualmente, o SDK do AzureCommunicationChat para iOS não oferece suporte à habilitação de bitcode, o seguinte problema do GitHub está rastreando isso.

Código de Exemplo

Encontre o código finalizado para este início rápido no GitHub.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa ou crie uma conta do Azure gratuitamente.
Um recurso ativo dos Serviços de Comunicação do Azure ou crie um recurso dos Serviços de Comunicação.
Um recurso ativo de Aplicativos Lógicos do Azure ou crie um aplicativo lógico em branco com o gatilho que você deseja usar. Atualmente, o conector de Chat dos Serviços de Comunicação fornece apenas ações, portanto, seu aplicativo lógico requer um gatilho, no mínimo.

Criar utilizador

Conclua estas etapas no Power Automate com o fluxo do Power Automate aberto no modo de edição.

Para adicionar uma nova etapa ao seu fluxo de trabalho usando o conector de Identidade dos Serviços de Comunicação:

No designer, na etapa em que você deseja adicionar a nova ação, selecione Nova etapa. Como alternativa, para adicionar a nova ação entre as etapas, mova o ponteiro sobre a seta entre essas etapas, selecione o sinal de adição (+) e selecione Adicionar uma ação.
Na caixa de pesquisa Escolha uma operação, insira Identidade dos Serviços de Comunicação. Na lista de ações, selecione Criar um usuário.
Insira a cadeia de conexão. Para obter a URL da cadeia de conexão no portal do Azure, vá para o recurso Serviços de Comunicação do Azure. No menu de recursos, selecione Teclas e, em seguida, selecione Cadeia de conexão. Selecione o ícone de cópia para copiar a cadeia de conexão.
Introduzir um nome para a ligação.
Selecione Mostrar opções avançadas e, em seguida, selecione o escopo do token. A ação gera um token de acesso e seu tempo de expiração com o escopo especificado. Essa ação também gera um ID de usuário que é uma identidade de usuário dos Serviços de Comunicação.
Em Item de Escopos de Token, selecione chat.
Selecione Criar. O ID de usuário e um token de acesso são mostrados.

Criar um tópico de bate-papo

Adicione uma nova ação.
Na caixa Escolha uma operação de pesquisa, digite Chat dos Serviços de Comunicação. Na lista de ações, selecione Criar thread de chat.
Insira a URL do ponto de extremidade dos Serviços de Comunicação. Para obter a URL do ponto de extremidade no portal do Azure, vá para o recurso Serviços de Comunicação do Azure. No menu de recursos, selecione Teclas e, em seguida, selecione Ponto de extremidade.
Introduzir um nome para a ligação.
Selecione o token de acesso que foi gerado na seção anterior e adicione uma descrição do tópico do thread de chat. Adicione o usuário criado e insira um nome para o participante.

Enviar uma mensagem

Adicione uma nova ação.
Na caixa Escolha uma operação de pesquisa, digite Chat dos Serviços de Comunicação. Na lista de ações, selecione Enviar mensagem para o tópico de chat.
Insira o token de acesso, ID do thread, conteúdo e nome.

Listar mensagens de thread de bate-papo

Para verificar se você enviou uma mensagem corretamente:

Adicione uma nova ação.
Na caixa Escolha uma operação de pesquisa, digite Chat dos Serviços de Comunicação. Na lista de ações, selecione Listar mensagens de thread de chat.
Insira o token de acesso e o ID do thread.

Teste seu aplicativo lógico

Para iniciar manualmente o fluxo de trabalho, na barra de ferramentas do designer, selecione Executar. O fluxo de trabalho cria um usuário, emite um token de acesso para esse usuário e, em seguida, remove o token e exclui o usuário. Para obter mais informações, consulte Como executar seu fluxo de trabalho.

Agora, selecione Listar mensagens de thread de bate-papo. Nas saídas da ação, verifique a mensagem que foi enviada.

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

Limpar recursos do fluxo de trabalho

Para limpar o fluxo de trabalho do aplicativo lógico e os recursos relacionados, veja como limpar os recursos dos aplicativos lógicos.

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele. Saiba mais sobre a limpeza de recursos.

Próximos passos

Neste guia de início rápido, você aprendeu como:

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

Experimente o aplicativo Chat Hero

Você também pode querer:

Introdução à biblioteca da interface do usuário
Saiba mais sobre os conceitos de chat
Familiarize-se com o SDK de bate-papo
Usando o SDK de bate-papo em seu aplicativo React Native .

Guia de início rápido: adicionar bate-papo ao seu aplicativo

Pré-requisitos

Configuração

Adicionar a extensão

Iniciar sessão na CLI do Azure

(Opcional) Usar operações de identidade da CLI do Azure sem passar um ponto de extremidade ou token de acesso

Armazene seu endpoint em uma variável de ambiente

Armazene seu token de acesso em uma variável de ambiente

Operações

Iniciar um tópico de bate-papo

Atualizar o tópico de um tópico de bate-papo

Listar todos os tópicos de bate-papo

Enviar uma mensagem para um tópico de chat

Listar mensagens de bate-papo em um thread de bate-papo

Receber uma mensagem de chat a partir de um tópico de chat

Enviar recibo de leitura

Adicionar um usuário como participante ao tópico de bate-papo

Listar participantes de threads em um thread de bate-papo

Remover um participante de um tópico de chat

Pré-requisitos

Configuração

Criar um novo aplicativo Web

Instalar os pacotes

Configurar a estrutura do aplicativo

Criar um cliente de chat

Executar o código

Modelo de objeto

Iniciar um tópico de bate-papo

Obter um cliente de thread de chat

Listar todos os tópicos de bate-papo

Enviar uma mensagem para um tópico de chat

Receber mensagens de chat a partir de um tópico de chat

Adicionar um usuário como participante ao tópico de bate-papo

Listar usuários em um tópico de bate-papo

Remover usuário de um tópico de bate-papo

Subscrever o estado da ligação de notificações em tempo real

Código de Exemplo

Pré-requisitos

Configuração

Criar uma aplicação Python nova

Instalar o SDK

Modelo de objeto

Criar um cliente de chat

Iniciar um tópico de bate-papo

Obter um cliente de thread de chat

Listar todos os tópicos de bate-papo

Enviar uma mensagem para um tópico de chat

Receber mensagens de chat a partir de um tópico de chat

Enviar recibo de leitura

Adicionar um usuário como participante ao tópico de bate-papo

Listar participantes de threads em um thread de bate-papo

Executar o código

Código de Exemplo

Pré-requisitos

Configuração

Criar uma nova aplicação Java

Adicionar as referências de pacote para o SDK de bate-papo

Modelo de objeto

Criar um cliente de chat

Iniciar um tópico de bate-papo

Listar tópicos de bate-papo

Obter um cliente de thread de chat

Enviar uma mensagem para um tópico de chat

Receber mensagens de chat a partir de um tópico de chat

Enviar recibo de leitura

Listar participantes do bate-papo

Adicionar um usuário como participante ao tópico de bate-papo

Executar o código

Código de Exemplo

Pré-requisitos

Configuração

Criar uma nova aplicação Android

Instalar as bibliotecas

Excluir metaarquivos em opções de empacotamento no root build.gradle

(Alternativa) Para instalar bibliotecas através do Maven

Configurar uma Função do Azure

Configure constantes de aplicativo:

Configurar os espaços reservados

Inicializar parâmetros do aplicativo

Criar um cliente de chat