Partilhar via

Adicionar bate-papo ao seu aplicativo

Adicione bate-papo em tempo real ao seu aplicativo usando o SDK de Chat dos Serviços de Comunicação. Este artigo descreve como usar o SDK de bate-papo para criar threads de bate-papo que permitem que os usuários tenham conversas uns com os outros. Para saber mais sobre os conceitos de bate-papo, consulte 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 respetiva 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 Serviços de Comunicação. Pode obter o ponto final 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 Utilizador. Certifique-se de definir o escopo para bate-papo e tome nota da string de token, bem como da string de user_id. Você também pode usar a CLI do Azure e executar o seguinte comando 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.

Configurar

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

Iniciar sessão na CLI do Azure

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

(Opcional) Utilizar as 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 a seguir. 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, talvez seja necessário reiniciar todos os programas em execução que precisem ler a variável de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

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 a seguir. Substitua <yourAccessToken> pelo seu token de acesso real.

Abra uma janela do console e digite o seguinte comando:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Depois de adicionar a variável de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisem ler a variável de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

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ê armazenou o ponto de extremidade e o token de acesso em variáveis de ambiente, como indicado anteriormente, não precisará passá-los para o comando.

az communication chat thread create --topic "<chatTopic>"
  • Use <chatTopic> para definir um tema para o 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 seu token de acesso obtido anteriormente ao executar o comando 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 endpoint dos Azure Communication Services.
  • Substitua <token> pelo token de acesso obtido anteriormente ao executar o comando 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>"
  • Opcional: Use <startTime> para especificar o primeiro ponto no tempo para receber mensagens de bate-papo.
  • Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
  • Substitua <token> pelo token de acesso que obteve anteriormente ao executar o comando 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 ao executar o comando 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 endpoint dos Azure Communication Services.
  • Substitua <token> pelo token de acesso obtido anteriormente ao executar o comando 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 que obtido anteriormente ao executar o comando 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 ao executar o comando 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 endpoint dos Serviços de Comunicação do Azure.
  • Substitua <token> pelo token de acesso obtido anteriormente ao executar o comando identity token issue.

Listar participantes num tópico 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 ao executar o comando identity token issue.

Remover um participante de um tópico de chat

Você pode remover um participante do 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 ao executar o comando identity token issue.

Pré-requisitos

  • Crie uma conta do Azure com uma assinatura ativa. Para obter detalhes, consulte Criar uma conta gratuitamente.

  • Instale Node.js versões 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ê precisa registrar seu ponto de extremidade de recurso e cadeia de conexão para este artigo.

  • 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 sequência do token, bem como a do 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 seguinte comando 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.

Configurar

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 seguintes SDKs do Communication Services para JavaScript.

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 em seu arquivo package.json .

Configurar a estrutura do aplicativo

Este artigo usa 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. Use 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 artigo.

Criar um cliente de chat

Para criar um cliente de chat em seu aplicativo Web, use 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 artigo não aborda a criação de uma camada de serviço para gerenciar tokens para seu aplicativo de chat. Para obter mais informações sobre a arquitetura de chat, consulte conceitos de chat. Para obter mais informações sobre tokens de acesso, consulte Tokens de acesso de usuário.

Dentro de client.js, use o endpoint e o token de acesso no código a seguir para adicionar a funcionalidade de chat usando o SDK de 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 de Serviços de Comunicação. Para obter mais informações, consulte Criar um recurso dos Serviços de Comunicação do Azure.
  • 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 navegador, você deve ver:

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.

Nome Descrição
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 a usa 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.

createChatThread quando resolvido, o método retorna um CreateChatThreadResult. Este modelo contém uma chatThread propriedade onde você pode acessar o id do thread recém-criado. Em seguida, pode usar o id para obter uma instância de um ChatThreadClient. 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á a seguinte mensagem no console:

Thread created: <thread_id>

Obter um cliente de thread de chat

O getChatThreadClient método retorna um chatThreadClient para um 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; deverá 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 [ChatThreadItem] é a resposta retornada de 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. Ele contém 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 o separador do navegador e verifique o console.

Message sent!, message id:<number>

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

Com 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 em vez 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, é possível recuperar as mensagens de bate-papo ao pesquisar o método listMessages 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 informações, consulte Tipos de mensagem.

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.

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 precisa 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 bate-papo;

  • 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 utilizador. Adicione este código no lugar do <ADD NEW PARTICIPANT TO THREAD> comentário em client.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 <LIST PARTICIPANTS IN A THREAD> comentário em client.js, atualize a guia do 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, você precisa rastrear os IDs dos participantes que você 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.

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

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 artigo no exemplo do GitHub Adicionar bate-papo ao seu aplicativo.

Pré-requisitos

  • 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ê precisa registrar seu ponto de extremidade de recurso e cadeia de conexão para este artigo.

  • Um token de acesso de usuário. Certifique-se de definir o escopo para bate-papo e registe a sequência de caracteres de token, bem como a sequência de caracteres de user_id. Você também pode usar a CLI do Azure e executar o seguinte comando 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, adicione todo o código-fonte deste artigo 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.

Nome Descrição
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 ChatCliente 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 que foi gerado durante os passos preliminares.

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 artigo não aborda a criação de uma camada de serviço para gerenciar tokens para seu aplicativo de chat, mas é recomendado. Para mais informações, consulte a seção "Arquitetura de bate-papo" em Conceitos de bate-papo > Arquitetura 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 obter o id do tópico de bate-papo 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 [ChatThreadItem] é a resposta retornada dos threads de 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 send_message para enviar uma mensagem para uma conversa que criaste, identificada 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 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. 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 ponto no tempo para receber mensagens.

Um iterador de [ChatMessage] é a resposta retornada das mensagens de 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 se identificam a partir do ChatMessage.type.

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

Enviar recibo de leitura

Você usa o método send_read_receipt para publicar um evento de confirmação de leitura num tópico, em nome de um utilizador.

  • 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, se um novo token de acesso e identidade estiver disponível 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 e 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 os participantes de um tópico de chat

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.
  • Utilize skip para ignorar os participantes até uma posição especificada na resposta.

Um iterador de [ChatParticipant] é a resposta retornada ao listar os participantes.

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 artigo no exemplo do GitHub Adicionar bate-papo ao seu aplicativo.

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ê precisa registrar o ponto de extremidade e a cadeia de conexão do seu recurso para este artigo.

  • Um token de acesso de usuário. Certifique-se de definir o escopo para bate-papo e anote a cadeia de token assim como a de user_id. Você também pode usar a CLI do Azure e executar o seguinte comando 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.

Configurar

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 seguinte comando para gerar o projeto Java a partir do maven-archetype-quickstart modelo.

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

O generate objetivo é criar um diretório com o mesmo nome do artifactId. Nesse diretório, o src/main/java directory contém o código-fonte do projeto, o src/test/java diretório contém a fonte de teste e o pom.xml arquivo é o Modelo de Objeto do Projeto ou POM do projeto.

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 chat

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.

Nome Descrição
ChatClient Esta classe é necessária para a funcionalidade de chat. Você o instancia com as suas informações de assinatura e usa-o para criar, recuperar e excluir threads.
ChatAsyncClient Essa classe é necessária para a funcionalidade de bate-papo assíncrono. Você instancia-o com as suas informações de subscrição e usa-o para criar, obter e excluir tópicos.
ChatThreadClient Esta classe é necessária para a funcionalidade Chat Thread. Você obtém uma instância através do ChatClient e a usa 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 assíncrona de thread de bate-papo. 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, use o endpoint do Serviço de Comunicações e o token de acesso que foi gerado como parte dos passos prévios. 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. ChatParticipant leva o usuário que você criou no Token de Acesso de Usuário.

CreateChatThreadResult é a resposta retornada da criação de um tópico de chat. Ele contém um getChatThread() método, que retorna o ChatThread objeto que pode ser usado para obter o cliente de thread a partir do qual você pode obter o ChatThreadClient 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 listChatThreads para recuperar uma lista de threads de bate-papo 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 sendMessage método para enviar uma mensagem para o 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 TEXT de conteúdo da mensagem de bate-papo ou HTML.
  • Use senderDisplayName para especificar o nome de exibição do remetente.
  • 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 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 indicando quando essa mensagem foi excluída. Para mensagens editadas, chatMessage.getEditedOn() retorna uma data/hora indicando quando a mensagem foi editada. O tempo original de criação da mensagem pode ser acessível usando chatMessage.getCreatedOn(), e pode ser usado para ordenar as mensagens.

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

Enviar recibo de leitura

Use o método sendReadReceipt para postar um evento de confirmação de leitura numa thread de chat, em nome de um utilizador. 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ê precisa começar obtendo um novo token de acesso e identidade para esse usuário. Antes de chamar addParticipants o 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 seu cliente de chat.

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

  • communicationIdentifier, obrigatório, é o CommunicationIdentifier que foi criado pelo CommunicationIdentityClient no User Access Token.
  • 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 pom.xml arquivo 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 artigo no exemplo do GitHub Adicionar bate-papo ao seu aplicativo.

Pré-requisitos

  • Crie uma conta do Azure com uma assinatura ativa. Para obter detalhes, consulte Criar uma conta gratuitamente.

  • Instale o Android Studio, usamos o Android Studio para criar um aplicativo Android e 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ê precisa registrar seu ponto de extremidade de recurso e cadeia de conexão para este artigo.

  • 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 artigo, criamos um thread com um participante inicial e, em seguida, adicionamos um segundo participante ao thread. Você também pode usar a CLI do Azure e executar o seguinte comando 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.

Configurar

Criar uma nova aplicação Android

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

Instalar as bibliotecas

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

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

Excluir arquivos meta nas 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 dependencies à seção do arquivo do seu aplicativo pom.xml , especificando sua ID de artefato e a 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

Para obter detalhes, consulte Integração do Azure Function. Recomendamos a integração com o Azure Functions para evitar a codificação fixa de parâmetros da aplicação.

Configurar 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 artigo, adicionamos nosso código ao MainActivitye visualizamos a saída no console. Este artigo não aborda a criação de uma interface do usuário. Na parte superior do arquivo, importe o Azure Communication Common, Azure Communication Chate outras bibliotecas do sistema:

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 a MainActivity.java se QUALQUER 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 de Chat de Comunicação do Azure para Android é < 2.0.0. Caso contrário, consulte a etapa 11 em Notificações por push do Android. Consulte o APP de exemplo da versão do SDK que você está consumindo para referência.

ACS_ENDPOINT, FIRST_USER_ID e FIRST_USER_ACCESS_TOKEN são retornados após a chamada da Função Azure. Para obter mais informações, consulte Integração do Azure Function. 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.

Nome Descrição
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 a usa 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 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, precisamos obter 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

Envie uma mensagem para o tópico de bate-papo 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, pode inscrever-se a novas mensagens recebidas e atualizar as mensagens existentes 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: quando você usa 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. Pode encontrar um problema de resolução de dependências. Você pode desativar o recurso de notificações em tempo real adicionando as seguintes informações de dependência no arquivo build.gradle da aplicação e, em vez disso, consultar a API GetMessages para mostrar mensagens recebidas aos utilizadores.

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 que, com essa atualização, se o aplicativo tentar entrar em contato com a API de notificação usando chatAsyncClient.startRealtimeNotifications() ou chatAsyncClient.addEventHandler(), ele gerará um erro de tempo de execução.

Notificações push

Para obter mais informações, consulte Notificações por push do Android.

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

Remova o segundo usuário do thread.

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

Enviamos o recibo de leitura da mensagem enviada anteriormente.

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 artigo no exemplo do GitHub Adicionar bate-papo ao seu aplicativo.

Pré-requisitos

  • 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ê precisa registrar seu ponto de extremidade de recurso e cadeia de conexão para este artigo.

  • Um token de acesso de utilizador. Certifique-se de definir o escopo para bate-papo e anote a cadeia de token, bem como a cadeia de user_id. Você também pode usar a CLI do Azure e executar o seguinte comando 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.

Configurar

Criar um novo aplicativo C#

Em uma janela de console (como cmd, PowerShell ou Bash), use o dotnet new comando para criar um novo aplicativo de console com o 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#.

Nome Descrição
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, use 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 artigo não aborda a criação de uma camada de serviço para gerenciar tokens para seu aplicativo de chat, embora seja recomendável. Para obter mais informações, consulte Arquitetura de bate-papo.

Copie os seguintes trechos de código e cole no Program.cs arquivo de origem.

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. Você pode atualizar o tópico depois de criar o tópico de bate-papo usando a UpdateTopic função.
  • Utilize a propriedade participants para passar uma lista de objetos ChatParticipant a serem adicionados ao fio de chat. O ChatParticipant objeto é inicializado com um CommunicationIdentifier objeto. CommunicationIdentifier pode ser do tipo CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, ou PhoneNumberIdentifier. Por exemplo, para obter um CommunicationIdentifier objeto, você precisa passar uma ID de acesso que você criou seguindo as instruções para Criar um 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 e assim por diante, 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 conversa em linha

O GetChatThreadClient método retorna um cliente de thread para um thread que já existe. Você pode usá-lo para executar operações no thread criado: adicionar membros, enviar mensagem e assim por diante. threadId é o ID exclusivo do tópico de bate-papo 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. Obrigatório.
  • Use type para o tipo de conteúdo da mensagem, como 'Texto' ou 'Html'. Se não for especificado, 'Texto' é definido.
  • Use senderDisplayName para especificar o nome de exibição do remetente. Caso não seja especificado, é definida uma string vazia.
  • Opcional: use metadata para incluir 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.
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 consultando o GetMessages método do cliente de thread do 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. As mensagens recebidas antes do tempo de deslocamento, mas editadas ou removidas depois, também sã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 indicando 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 acessível usando chatMessage.CreatedOn, e ela pode ser utilizada para organizar as mensagens.

GetMessages Retorna diferentes tipos de mensagens. Você pode identificar o tipo a partir do chatMessage.Type. Os tipos são:

  • Text: Mensagem de chat normal enviada por um membro do tópico.

  • Html: Uma mensagem de texto formatada. Atualmente, os usuários dos Serviços de Comunicação não podem enviar mensagens RichText. Esse tipo de mensagem é suportado para 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 está atualizado. (somente leitura)

  • ParticipantAdded: Mensagem do sistema que indica que um ou mais participantes são adicionados à conversa (apenas leitura).

  • ParticipantRemoved: Mensagem do sistema que indica que um participante foi removido do tópico de chat.

Para obter mais informações, 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 chamar AddParticipants, certifique-se de adquirir um novo token de acesso e identidade para esse usuário. O usuário precisa 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 da discussão

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 o usuário leu a mensagem.

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 artigo no exemplo do GitHub Adicionar bate-papo ao seu aplicativo.

Pré-requisitos

  • 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 este artigo 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ê precisa registrar seu ponto de extremidade de recurso e cadeia de conexão para este artigo.

  • 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 string do token, bem como a string do user_id. Neste artigo, 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 seguinte comando 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.

Configurar

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

Utilize 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 target ChatQuickstart:

pod 'AzureCommunicationChat', '~> 1.3.6'

Instale as dependências com o seguinte comando: pod install. 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.swift.

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

Na parte superior do viewController.swift, importe as AzureCommunication e AzureCommunicationChat 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, usamos um semáforo para sincronizar seu código. Nas etapas seguintes, substituis os marcadores de posição por código de exemplo utilizando a biblioteca Chat dos Serviços de Comunicações Azure.

Criar um cliente de chat

Para criar um cliente de chat, use o seu ponto final dos Serviços de Comunicação e o token de acesso que foi gerado como parte das etapas preliminares.

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

Este artigo não aborda a criação de uma camada de serviço para gerenciar tokens para seu aplicativo de chat, mas recomendamos isso. Saiba mais sobre a arquitetura de bate-papo

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

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.

Nome Descrição
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 ChatCliente 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 tópico 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 seguinte trecho de código:

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, use o threadId da resposta retornada para o gestor de finalizaçã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 tópico de conversa

O createClient método retorna um ChatThreadClient para um 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 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. Ele contém um ID, que é o ID exclusivo da mensagem.

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

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 sendReadReceipt para publicar um evento de confirmação de leitura num thread de bate-papo, em nome de um utilizador. messageId é o ID exclusivo da mensagem de chat que foi lida.

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

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

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

Substitua o comentário <RECEIVE MESSAGES> pelo código seguinte. 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 recorrendo ao método listMessages 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, certifique-se de que adquiriu um novo token de acesso e identidade para esse utilizador. O usuário precisa do token de acesso para inicializar seu cliente de chat.

Use o método add de ChatThreadClient para adicionar um ou mais participantes à conversa de 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 listParticipants para obter todos os participantes de uma conversa de bate-papo específica.

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 é suportado pelo IOS SDK na versão 1.3.0.

Para obter mais informações, consulte Ativar notificação por push em seu aplicativo de bate-papo.

Executar o código

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

Nota: Defina Build Settings > Build Options > Enable Bitcode como No. Atualmente, o SDK do AzureCommunicationChat para iOS não suporta a ativação do bitcode, o seguinte problema do GitHub está a rastrear o problema.

Código de exemplo

Encontre o código finalizado para este artigo no exemplo do GitHub Adicionar bate-papo ao seu aplicativo.

Pré-requisitos

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:

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

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

    Captura de tela que mostra a ação Criar usuário do conector de Identidade dos Serviços de Comunicação do Azure.

  3. Insira a cadeia de conexão. Para obter o URL da string de conexão no portal do Azure, vá ao recurso de 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.

    Captura de ecrã que mostra o painel Chaves de um recurso dos Serviços de Comunicação do Azure.

  4. Introduzir um nome para a ligação.

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

    Captura de tela que mostra o conector de Identidade dos Serviços de Comunicação do Azure Criar opções de ação do usuário.

  6. Em Item de Escopos de Token, selecione chat.

    Captura de ecrã que mostra as opções avançadas do conector de Chat dos Serviços de Comunicação do Azure.

  7. Selecione Criar. O ID de usuário e um token de acesso são mostrados.

Criar um tópico de chat

  1. Adicione uma nova ação.

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

    Captura de ecrã que mostra o conector de Chat dos Serviços de Comunicação do Azure na ação de criar um thread de chat.

  3. Insira o URL do ponto final dos Serviços de Comunicação. Para obter a URL do ponto de extremidade no portal 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.

  4. Introduzir um nome para a ligação.

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

    Captura de ecrã que mostra a caixa de diálogo de ação Criar tópico de chat do conector dos Serviços de Comunicação do Azure.

Enviar uma mensagem

  1. Adicione uma nova ação.

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

    Captura de ecrã que mostra a ação Enviar mensagem de chat do conector de Chat dos Serviços de Comunicação do Azure.

  3. Insira o token de acesso, ID do thread, conteúdo e nome.

    Captura de ecrã que mostra a janela de ação do conector dos Serviços de Comunicação do Azure Enviar mensagem de chat.

Listar mensagens de thread de bate-papo

Para verificar se você enviou uma mensagem corretamente:

  1. Adicione uma nova ação.

  2. Na caixa Escolha uma operação de pesquisa, digite Chat dos Serviços de Comunicação. Na lista de ações, selecione Listar mensagens da thread de chat.

    Captura de tela que mostra a ação Listar mensagens de chat do conector de Chat dos Serviços de Comunicação do Azure.

  3. Insira o token de acesso e o ID do thread.

    Captura de tela que mostra a caixa de diálogo de ação Listar mensagens de chat do conector de Chat dos Serviços de Comunicação do Azure.

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.

Captura de ecrã que mostra os resultados da ação Enviar mensagem de chat do conector de Chat dos Serviços de Comunicação do Azure.

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.

Limpar recursos

Para 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. Para obter mais informações, consulte Limpeza de recursos.

Próximos passos

Este artigo descreveu 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