Compartilhar via

Início Rápido: Adicionar o chat ao seu aplicativo

  • Artigo

Comece a usar os Serviços de Comunicação do Azure com o SDK de Chat dos Serviços de Comunicação para adicionar chat em tempo real ao seu aplicativo. Neste guia de início rápido, usaremos o SDK de Chat para criar conversas de chat que permitem que os usuários tenham conversas entre si. Para saber mais sobre os conceitos do Chat, acesse a documentação conceitual do chat.

Pré-requisitos

  • Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

  • Um recurso e uma cadeia de conexão ativos dos Serviços de Comunicação. Crie um recurso dos Serviços de Comunicação.

  • Instale a CLI do Azure.

  • Anote seu ponto de extremidade de recurso dos Serviços de Comunicação. É possível obter o ponto de extremidade no portal do Azure. Como alternativa, é possível encontrar a URL do ponto de extremidade na cadeia de conexão. A URL dele é aquela que vem depois de endpoint= e começa com https://.

  • Um token de acesso do usuário. Defina o escopo como chat e anote a cadeia de caracteres do token, bem como a cadeia de caracteres da user_id. Você também pode usar a CLI do Azure e executar o comando abaixo com a 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, confira Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configurando

Adicionar a extensão

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

az extension add --name communication

Entrar na CLI do Azure

Você precisará entrar na CLI do Azure. Para se conectar, execute o comando az login no terminal e forneça suas credenciais.

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

Armazenar o ponto de extremidade em uma variável de ambiente

É possível configurar a variável de ambiente AZURE_COMMUNICATION_ENDPOINT para usar operações de chat da CLI do Azure sem precisar usar --endpoint a fim de transmitir o ponto de extremidade. Para configurar uma variável de ambiente, abra uma janela do console e selecione o sistema operacional nas guias abaixo. Substitua <yourEndpoint> pelo seu ponto de extremidade.

Abra uma janela do console e insira 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 precisarem ler a variável de ambiente, incluindo a janela do console. Por exemplo, se estiver usando o Visual Studio como seu editor, reinicie-o antes de executar o exemplo.

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

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

Abra uma janela do console e insira 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 precisarem ler a variável de ambiente, incluindo a janela do console. Por exemplo, se estiver usando o Visual Studio como seu editor, reinicie-o antes de executar o exemplo.

Operations

Iniciar uma conversa de chat

Use o comando thread create para criar uma conversa de chat.

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

Se você tiver armazenado o ponto de extremidade e o token de acesso em variáveis de ambiente conforme indicado acima, não será preciso transmiti-los ao comando.

az communication chat thread create --topic "<chatTopic>"
  • Use <chatTopic> para dar um tópico à conversa. É possível atualizar o tópico após a criação da conversa de chat usando o comando thread update-topic.
  • Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
  • Substitua <token> pelo token de acesso obtido anteriormente por meio da execução do comando identity token issue.

Atualizar o tópico de uma conversa de chat

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"
  • Substitua <chatThreadId> pela ID da conversa de chat.
  • Substitua <chatTopic> pelo novo tópico de chat que você deseja definir.
  • Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
  • Substitua <token> pelo token de acesso obtido anteriormente por meio da execução do comando identity token issue.

Listar todas as conversas de chat

O comando thread list retorna a lista de conversas de chat de um usuário.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Opcionalmente, use <startTime> para especificar o momento inicial a partir do qual receber mensagens de chat.
  • Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
  • Substitua <token> pelo token de acesso obtido anteriormente por meio da execução do comando identity token issue.

Enviar uma mensagem para uma conversa de chat

Use o comando message send para enviar uma mensagem para uma conversa de chat que você criou, identificada por threadId.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"
  • Substitua <chatThreadId> pela ID da conversa de chat.
  • Use <content> para fornecer o conteúdo da mensagem de chat.
  • Use <messageType> para especificar o tipo do 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.
  • Opcionalmente, use <displayName> 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 por meio da execução do comando identity token issue.

Listar mensagens em uma conversa de chat

O comando message list retorna a lista de mensagens em uma conversa de chat.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Substitua <chatThreadId> pela ID da conversa de chat.
  • Opcionalmente, use <startTime> para especificar o momento inicial a partir do qual receber mensagens de chat.
  • Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
  • Substitua <token> pelo token de acesso obtido anteriormente por meio da execução do comando identity token issue.

Receber mensagens de uma conversa de chat

É possível recuperar mensagens de chat usando o comando message list.

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Substitua <chatThreadId> pela ID da conversa de chat.
  • Substitua <messageId> pela ID da mensagem que será recuperada.
  • Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
  • Substitua <token> pelo token de acesso obtido anteriormente por meio da execução do comando identity token issue.

Enviar confirmação de leitura

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

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Substitua <chatThreadId> pela ID da conversa de chat.
  • Substitua <messageId> para especificar a ID da mensagem mais recente 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 por meio da execução do comando identity token issue.

Adicionar um usuário como participante ao thread de chat

Depois de criar uma conversa de chat, você poderá adicionar usuários a ela e removê-los dela. Ao adicionar usuários, você permite a eles acesso para enviar mensagens à conversa de chat e adicionar ou remover outros participantes. Antes de chamar o comando participant add, verifique se você adquiriu um token de acesso e uma 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> pela ID da conversa de chat.
  • Substitua <userId> por seu userId.
  • Opcionalmente, use <displayName> para especificar o nome de exibição do remetente.
  • Opcionalmente, use <startTime> para especificar o momento inicial a partir do qual receber mensagens de chat.
  • Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
  • Substitua <token> pelo token de acesso obtido anteriormente por meio da execução do comando identity token issue.

Listar participantes do thread em um thread de chat

Assim como adicionar um participante, você também pode listar participantes de uma conversa.

Use o comando participant list para recuperar os participantes da conversa.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"
  • Substitua <chatThreadId> pela ID da conversa de chat.
  • Opcionalmente, use o <skip> para pular 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 por meio da execução do comando identity token issue.

Remover um participante de uma conversa de chat

É possível remover um participante de uma conversa de chat usando o comando 'participant remove'.

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"
  • Substitua <chatThreadId> pela ID da conversa de chat.
  • Substitua <userId> pela ID de usuário que será removida da conversa de chat.
  • Substitua <endpoint> pelo ponto de extremidade dos Serviços de Comunicação do Azure.
  • Substitua <token> pelo token de acesso obtido anteriormente por meio da execução do comando identity token issue.

Pré-requisitos

Antes de começar, é preciso:

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

  • Instalar as versões de LTS Ativo e de LTS de Manutenção do Node.js.

  • Criar um recurso dos Serviços de Comunicação do Azure. Para obter detalhes, confira Criar um recurso dos Serviços de Comunicação do Azure. Você precisará registrar o ponto de extremidade e a cadeia de conexão do recurso para este guia de início rápido.

  • Crie três Usuários dos Serviços de Comunicação do Azure e emita para eles um Token de Acesso do Usuário. Defina o escopo como chat e anote a cadeia de caracteres do token, bem como a cadeia de caracteres da user_id. A demonstração completa cria um thread com dois participantes iniciais e adiciona um terceiro participante ao thread. Você também pode usar a CLI do Azure e executar o comando abaixo com a 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, confira Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configurando

Criar um aplicativo Web

Primeiro, abra o terminal ou a janela de comando para criar um 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 comando npm install para instalar os SDKs dos Serviços de Comunicação abaixo 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 opção --save lista a biblioteca como uma dependência no arquivo package.json.

Configurar o framework de aplicativos

Este guia de início rápido usa o pacote 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 projeto. Usaremos esse arquivo como modelo para adicionar a funcionalidade de chat usando o SDK de Chat da 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 projeto chamado client.js para conter a lógica do aplicativo deste guia de início rápido.

Criar um cliente de chat

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

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

Dentro de client.js, use o ponto de extremidade e o token de acesso no código abaixo para adicionar 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!');

Executar o código

Execute o comando a seguir para executar o aplicativo:

npx parcel index.html

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

Azure Communication Chat client created!

Modelo de objeto

As classes e as 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 Essa classe é necessária para a funcionalidade de chat. Crie uma instância dela com suas informações de assinatura e use-a para criar, obter, excluir threads e assinar eventos de chat.
ChatThreadClient Essa classe é necessária para a funcionalidade de conversa de chat. Obtenha uma instância por meio de ChatClient e use-a para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter usuários e enviar notificações de digitação e confirmações de leitura.

Iniciar uma conversa de chat

Use o método createThread para criar uma conversa de chat.

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

  • Use topic para fornecer um tópico para esse chat. Os tópicos podem ser atualizados após a conversa do chat ser criada usando a função UpdateThread.
  • Use participants para listar os participantes a serem adicionados ao thread de chat.

Quando resolvido, o método createChatThread retorna um CreateChatThreadResult. Esse modelo contém uma propriedade chatThread na qual você pode acessar o id do thread recém-criado. Você pode usar o id para obter uma instância de um ChatThreadClient. O ChatThreadClient pode então ser usado para executar a operação 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 conversa de chat

O método getChatThreadClient retorna um chatThreadClient para uma conversa que já existe. Ele pode ser usado para executar operações no thread criado: adicionar participantes, enviar mensagens etc. threadId é a ID exclusiva 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 comentário <CREATE CHAT THREAD CLIENT> em client.js, atualize a guia do navegador e verifique o console. Você verá:

Chat Thread client for threadId: <threadId>

Listar todas as conversas de chat

O método listChatThreads retorna um PagedAsyncIterableIterator do tipo ChatThreadItem. Ele pode ser usado para listar todas as conversas de chat. Um iterador de [ChatThreadItem] é a resposta retornada pela listagem de threads

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

Enviar uma mensagem para uma conversa de chat

Use o método sendMessage para enviar uma mensagem a uma conversa identificada por threadId.

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

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

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

  • Use senderDisplayName para especificar o nome de exibição do remetente;
  • Use type para especificar o tipo de mensagem, como 'texto' ou 'html';
  • Use metadata opcionalmente para incluir outros dados que você queira 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 caso de uso específico. Por exemplo, ao compartilhar um link de arquivo na mensagem, pode ser interessante adicionar "hasAttachment:true" nos metadados para que o aplicativo do destinatário possa analisá-la e exibi-la de acordo.

SendChatMessageResult é a resposta retornada do envio de uma mensagem; ela contém uma ID, que é a ID exclusiva 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 comentário <SEND MESSAGE TO A CHAT THREAD> em client.js, atualize a guia do navegador e verifique o console.

Message sent!, message id:<number>

Receber mensagens de chat de uma conversa de chat

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

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

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

Como alternativa, você pode recuperar mensagens de chat sondando 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 comentário <LIST MESSAGES IN A CHAT THREAD> em client.js. Atualize a guia e, no console, você encontrará a lista de mensagens enviadas nesse thread de chat.

listMessages retorna diferentes tipos de mensagens, que podem ser identificadas por chatMessage.type.

Para obter mais detalhes, confira Tipos de mensagem.

Adicionar um usuário como participante ao thread de chat

Depois que uma conversa de chat é criada, você pode adicionar e remover usuários nela. Ao adicionar usuários, você permite a eles acesso para enviar mensagens ao thread de chat e adicionar/remover outros participantes.

Antes de chamar o método addParticipants, adquira um novo token de acesso e uma identidade para esse usuário. O usuário precisará desse token de acesso para inicializar o cliente de chat.

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

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

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

await chatThreadClient.addParticipants(addParticipantsRequest);

Substitua NEW_PARTICIPANT_USER_ID por uma nova ID de usuário. Adicione este código no lugar do comentário <ADD NEW PARTICIPANT TO THREAD> em client.js

Listar os usuários de uma conversa de chat

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

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

Remover um usuário de uma conversa de chat

Assim como adicionar um participante, você pode remover participantes de um thread de chat. Para removê-los, acompanhe as IDs dos participantes que você adicionou.

Use o método removeParticipant, em que participant é o usuário de comunicação a ser removido da conversa.


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

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

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

Assinatura para eventos realTimeNotificationConnected e realTimeNotificationDisconnected permite que você saiba quando a conexão com o servidor de chamada 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
});

Exemplo de código

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

Pré-requisitos

Antes de começar, é preciso:

Configurando

Criar um novo aplicativo Python

Abra a janela Comando ou o terminal para criar um diretório para o seu aplicativo e acesse-o.

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 do programa, incluindo um tratamento de exceções básico. Nas seções a seguir, você adicionará todo o código-fonte deste guia de início rápido a esse 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 as 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 Essa classe é necessária para a funcionalidade de chat. Crie uma instância dela com suas informações de assinatura e use-a para criar, obter e excluir conversas.
ChatThreadClient Essa classe é necessária para a funcionalidade de conversa de chat. Você obtém uma instância por meio do ChatClient e a usa para enviar, receber, atualizar ou excluir mensagens. Você também pode usá-la para adicionar, remover e obter usuários, enviar notificações de digitação e confirmações de leitura.

Criar um cliente de chat

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

pip install azure-communication-identity

from azure.communication.chat import ChatClient, CommunicationTokenCredential

endpoint = "<replace with your resource endpoint>"
chat_client = ChatClient(endpoint, CommunicationTokenCredential("<Access Token>"))

Este início rápido não abrange a criação de uma camada de serviço para gerenciar tokens em seu aplicativo de chat, embora isso seja recomendado. Para obter mais informações, confira a seção "Arquitetura de chat" dos Conceitos de chat.

Iniciar uma conversa de chat

Use o método create_chat_thread para criar uma conversa de chat.

  • Use topic para dar um tópico à conversa. Atualize o tópico após a criação da conversa de chat usando a função update_thread.
  • Use thread_participants para listar o ChatParticipant a ser adicionado à conversa de chat. O ChatParticipant usa o tipo CommunicationUserIdentifier como user.

CreateChatThreadResult é o resultado retornado da criação de uma conversa. Use-o para buscar a id da conversa de chat criada. Em seguida, essa id pode ser usada para buscar um objeto ChatThreadClient usando o método get_chat_thread_client. Use ChatThreadClient para executar outras operações de chat nessa conversa de chat.

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 conversa de chat

O método get_chat_thread_client retorna um cliente de conversa para uma conversa que já existe. Você pode usá-lo para executar operações na conversa criada. Por exemplo, você pode adicionar participantes e enviar mensagens. thread_id é a ID exclusiva da conversa de chat existente.

Use ChatThreadClient para executar outras operações de chat nessa conversa de chat.

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

Listar todas as conversas de chat

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

  • Use start_time para especificar o ponto mais antigo no tempo e obter conversas de chat.
  • Use results_per_page para especificar o número máximo de conversas de chat retornadas por página.

Um iterador de [ChatThreadItem] é a resposta retornada pela listagem de conversas.

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 uma conversa de chat

Use o método send_message para enviar uma mensagem para uma conversa de chat recém-criada, identificada pela thread_id.

  • Use content para fornecer o conteúdo da mensagem de chat.
  • Use chat_message_type para especificar o tipo do 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 dados adicionais que você queira 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 caso de uso específico. Por exemplo, ao compartilhar um link de arquivo na mensagem, pode ser interessante adicionar "hasAttachment:true" nos metadados para que o aplicativo do destinatário possa analisá-la e exibi-la de acordo.

SendChatMessageResult é a resposta retornada do envio de uma mensagem. Ela contém uma ID, que é a ID exclusiva 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 de uma conversa de chat

Recupere mensagens de chat sondando o método list_messages em intervalos especificados.

  • Use results_per_page para especificar o número máximo de mensagens retornadas por página.
  • Use start_time para especificar o ponto mais antigo no tempo e obter mensagens.

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

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 última versão da mensagem, incluindo as edições ou as exclusões ocorridas na mensagem usando update_message e delete_message. Para as mensagens excluídas, ChatMessage.deleted_on retorna um valor de datetime indicando quando a mensagem foi excluída. Para as mensagens editadas, ChatMessage.edited_on retorna um valor de datetime indicando quando a mensagem foi editada. Acesse a hora original da criação da mensagem usando ChatMessage.created_on, que pode ser usado para ordenar as mensagens.

list_messages retorna diferentes tipos de mensagens, que podem ser identificadas por ChatMessage.type.

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

Enviar confirmação de leitura

Use o método send_read_receipt para postar um evento de confirmação de leitura em uma conversa, em nome de um usuário.

  • Use message_id para especificar a ID da mensagem mais recente 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 thread de chat

Depois de criar uma conversa de chat, você poderá adicionar usuários a ela e removê-los dela. Ao adicionar usuários, você permite a eles acesso para enviar mensagens à conversa de chat e adicionar ou remover outros participantes. Antes de chamar o método add_participants, adquira um novo token de acesso e uma identidade para esse usuário. O usuário precisará desse token de acesso para inicializar o cliente de chat.

Adicione um ou mais usuários à conversa de chat usando o método add_participants, desde que um novo token de acesso e uma identidade sejam disponibilizados a todos os usuários.

Um list(tuple(ChatParticipant, CommunicationError)) é retornado. Quando o participante é adicionado com êxito, uma lista vazia é esperada. Caso você encontre um erro ao adicionar um participante, a lista é preenchida com os participantes com falha, junto com o erro encontrado.

from azure.communication.identity import CommunicationIdentityClient
from azure.communication.chat import ChatParticipant
from datetime import datetime

# create 2 users
identity_client = CommunicationIdentityClient.from_connection_string('<connection_string>')
new_users = [identity_client.create_user() for i in range(2)]

# # conversely, you can also add an existing user to a chat thread; provided the user_id is known
# from azure.communication.identity import CommunicationUserIdentifier
#
# user_id = 'some user id'
# user_display_name = "Wilma Flinstone"
# new_user = CommunicationUserIdentifier(user_id)
# participant = ChatParticipant(
#     identifier=new_user,
#     display_name=user_display_name,
#     share_history_time=datetime.utcnow())

participants = []
for _user in new_users:
  chat_thread_participant = ChatParticipant(
    identifier=_user,
    display_name='Fred Flinstone',
    share_history_time=datetime.utcnow()
  ) 
  participants.append(chat_thread_participant) 

response = chat_thread_client.add_participants(participants)

def decide_to_retry(error, **kwargs):
    """
    Insert some custom logic to decide if retry is applicable based on error
    """
    return True

# verify if all users has been successfully added or not
# in case of partial failures, you can retry to add all the failed participants 
retry = [p for p, e in response if decide_to_retry(e)]
if retry:
    chat_thread_client.add_participants(retry)

Listar participantes do thread em um thread de chat

Assim como adicionar um participante, você também pode listar participantes de uma conversa.

Use list_participants para recuperar os participantes do thread de chat. Os dois seguintes comandos são opcionais:

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

Um iterador de [ChatParticipant] é a resposta retornada pela listagem de 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 do seu diretório de aplicativo com o comando python.

python start-chat.py

Exemplo de código

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

Pré-requisitos

Configurando

Criar um aplicativo Java

Abra o terminal ou a janela de comando e navegue até o diretório no qual você deseja criar o seu aplicativo Java. Execute o comando abaixo para gerar o projeto Java no modelo maven-archetype-quickstart.

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

Você observará que a meta 'gerar' criou um diretório com o mesmo nome que artifactId. Nesse diretório, o src/main/java directory contém o código-fonte do projeto, o diretório src/test/java contém a fonte de teste e o arquivo pom.xml é o Modelo de Objeto do Projeto ou POM do projeto.

Atualize o arquivo POM do seu aplicativo para usar o 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 ao SDK de Chat

Em seu arquivo POM, referencie o pacote azure-communication-chat com as APIs do Chat:

<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, o cliente precisa fazer referência ao pacote azure-communication-common:

<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 as 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 Essa classe é necessária para a funcionalidade de chat. Crie uma instância dela com suas informações de assinatura e use-a para criar, obter e excluir conversas.
ChatAsyncClient Essa classe é necessária para a funcionalidade de Chat assíncrona. Crie uma instância dela com suas informações de assinatura e use-a para criar, obter e excluir conversas.
ChatThreadClient Essa classe é necessária para a funcionalidade de conversa de chat. Obtenha uma instância por meio de ChatClient e use-a para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter usuários e enviar notificações de digitação e confirmações de leitura.
ChatThreadAsyncClient Essa classe é necessária para a funcionalidade de Conversa de Chat assíncrona. Obtenha uma instância por meio de ChatAsyncClient e use-a para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter usuários, enviar notificações de digitação e confirmações de leitura.

Criar um cliente de chat

Para criar um cliente de chat, você usará o ponto de extremidade do Serviço de Comunicação e o token de acesso que foi gerado como parte das etapas de pré-requisito. Os tokens de acesso do 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 no servidor, transmita-os novamente para um dispositivo cliente. Você precisa usar a classe CommunicationTokenCredential do SDK Comum para passar o token para seu cliente de chat.

Saiba mais sobre a Arquitetura de Chat

Ao adicionar as instruções de importação, lembre-se de adicionar somente 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 pelo 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 uma conversa de chat

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

  • Use o parâmetro topic do construtor para fornecer um tópico a esse chat; o tópico pode ser atualizado depois que a conversa de chat é criada por meio da função UpdateThread.
  • Use participants para listar os participantes do thread a serem adicionados a ele. ChatParticipant usa o usuário que você criou no guia de início rápido do Token de Acesso do Usuário.

CreateChatThreadResult é a resposta retornada pela criação de um thread de chat. Ele contém um método getChatThread() que retorna o objeto ChatThread. Esse objeto pode ser usado a fim de obter o cliente da conversa do qual é possível coletar o ChatThreadClient para executar operações na conversa criada: adicionar participantes, enviar mensagem etc. O objeto ChatThread também contém o método getId() que recupera a ID exclusiva da conversa.

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 threads de chat

Use o método listChatThreads para recuperar uma lista de threads de chat existentes.

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

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

Obter um cliente de conversa de chat

O método getChatThreadClient retorna um cliente de conversa para uma conversa que já existe. Ele pode ser usado para executar operações no thread criado: adicionar participantes, enviar mensagens etc. chatThreadId é a ID exclusiva do thread de chat existente.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Enviar uma mensagem para uma conversa de chat

Use o método sendMessage para enviar uma mensagem à conversa criada, identificada por chatThreadId. sendChatMessageOptions é usado para descrever a solicitação de mensagem de chat.

  • Use content para fornecer o conteúdo da mensagem de chat.
  • Use type para especificar o tipo de conteúdo de mensagem de chat, TEXTO ou HTML.
  • Use senderDisplayName para especificar o nome de exibição do remetente.
  • Use metadata opcionalmente para incluir dados adicionais que você queira 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 caso de uso específico. Por exemplo, ao compartilhar um link de arquivo na mensagem, é possível adicionar hasAttachment:true nos metadados para que o aplicativo do destinatário possa analisá-lo e exibi-lo adequadamente.

A resposta sendChatMessageResult contém um id, que é a ID exclusiva 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 de uma conversa de chat

Você pode recuperar mensagens de chat sondando o método listMessages no cliente da conversa de chat em intervalos especificados.

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

listMessages retorna a última versão da mensagem, incluindo as edições ou as exclusões que ocorreram na mensagem usando .editMessage() e .deleteMessage(). Para mensagens excluídas, chatMessage.getDeletedOn() retorna um valor datetime que indica quando a mensagem foi excluída. Para as mensagens editadas, chatMessage.getEditedOn() retorna um datetime indicando quando a mensagem foi editada. A hora original da criação da mensagem pode ser acessada usando chatMessage.getCreatedOn() e pode ser usada para ordenar as mensagens.

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

Enviar confirmação de leitura

Use o método sendReadReceipt para postar um evento de confirmação de leitura em um thread de chat, em nome de um usuário. chatMessageId é a ID exclusiva da mensagem de chat lida.

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

Listar participantes do chat

Use listParticipants para recuperar uma coleção paginada que contém os participantes do thread de chat identificado 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 thread de chat

Depois que uma conversa de chat é criada, você pode adicionar e remover usuários nela. Ao adicionar usuários, você permite a eles acesso para enviar mensagens ao thread de chat e adicionar/remover outros participantes. Você precisará começar obtendo um novo token de acesso e uma identidade para esse usuário. Antes de chamar o método addParticipants, verifique se você adquiriu um novo token de acesso e uma nova identidade para esse usuário. O usuário precisará desse token de acesso para inicializar o cliente de chat.

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

  • communicationIdentifier, obrigatório, é o CommunicationIdentifier que você criou por CommunicationIdentityClient no início rápido do Token de Acesso do Usuário.
  • displayName, opcional, é o nome de exibição do participante do thread.
  • shareHistoryTime, opcional, é a hora a partir da qual o histórico de chats é compartilhado com o participante. Para compartilhar o histórico desde o início da conversa de chat, defina essa propriedade como qualquer data igual ou inferior à hora de criação da conversa. Para não compartilhar nenhum histórico anterior ao momento em que o participante foi adicionado, defina-a como a data atual. Para compartilhar o histórico parcial, defina-o como a data necessária.
List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

CommunicationUserIdentifier identity3 = new CommunicationUserIdentifier("<USER_3_ID>");
CommunicationUserIdentifier identity4 = new CommunicationUserIdentifier("<USER_4_ID>");

ChatParticipant thirdThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity3)
    .setDisplayName("Display Name 3");

ChatParticipant fourthThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity4)
    .setDisplayName("Display Name 4");

participants.add(thirdThreadParticipant);
participants.add(fourthThreadParticipant);

chatThreadClient.addParticipants(participants);

Executar o código

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

mvn compile

Em seguida, compile o pacote.

mvn package

Execute o comando mvn a seguir para executar o aplicativo.

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

Exemplo de código

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

Pré-requisitos

Antes de começar, é preciso:

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

  • Instalar o Android Studio. Usaremos o Android Studio a fim de criar um aplicativo Android para o início rápido para instalar dependências.

  • Criar um recurso dos Serviços de Comunicação do Azure. Para obter detalhes, confira Criar um recurso dos Serviços de Comunicação do Azure. Você precisará registrar o ponto de extremidade e a cadeia de conexão do recurso para este guia de início rápido.

  • Crie dois Usuários dos Serviços de Comunicação e emita para eles um Token de Acesso do Usuário. Defina o escopo como chat e anote a cadeia de caracteres do token e a cadeia de caracteres da user_id. Neste guia de início rápido, criaremos um thread com um participante inicial e adicionaremos um segundo participante a ele. Você também pode usar a CLI do Azure e executar o comando abaixo com a 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, confira Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configurando

Criar um aplicativo Android

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

Instalar as bibliotecas

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

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

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

Exclua os metarquivos nas opções de empacotamento na raiz 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 por meio do Maven

Para importar a biblioteca para seu projeto usando o sistema de build do Maven, adicione-a à seção dependencies do arquivo pom.xml do seu aplicativo, especificando a 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 a Função do Azure

Confira a integração do Azure Functions para obter detalhes. É altamente recomendável integrar-se ao Azure Function para evitar o hard-coding dos parâmetros de aplicativo.

Configurar constantes de aplicativo:

Crie uma classe ApplicationConstants que armazena todas as constantes de 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 arquivo MainActivity.java. Neste guia de início rápido, adicionaremos nosso código a MainActivity e veremos a saída no console. Este guia de início rápido não aborda a criação de uma interface do usuário. Na parte superior do arquivo, importe Azure Communication Common, Azure Communication Chat e as outras bibliotecas:

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

Observação

A inicialização ApplicationConstants precisará 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 do 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 aplicativo 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 da chamada ao Azure Function. Confira a integração do Azure Functions para obter detalhes. Usamos a resposta de chamar o Azure Function para inicializar a lista de parâmetros:

  • ACS_ENDPOINT: o ponto de extremidade do recurso dos Serviços de Comunicação.
  • FIRST_USER_ID e SECOND_USER_ID: as IDs de usuário válidas dos Serviços de Comunicação geradas 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 os 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 as 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 Essa classe é necessária para a funcionalidade de chat. Crie uma instância dela com suas informações de assinatura e use-a para criar, obter, excluir threads e assinar eventos de chat.
ChatThreadClient/ChatThreadAsyncClient Essa classe é necessária para a funcionalidade de conversa de chat. Obtenha uma instância por meio de ChatClient e use-a para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter usuários e enviar notificações de digitação e confirmações de leitura.

Iniciar uma conversa de chat

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

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

// 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 conversa de chat

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

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 uma conversa de chat

Enviaremos a mensagem para essa conversa agora.

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

// 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 de uma conversa de chat

Notificações em tempo real

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

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


// Start real time notification
chatAsyncClient.startRealtimeNotifications(firstUserAccessToken, getApplicationContext());

// Register a listener for chatMessageReceived event
chatAsyncClient.addEventHandler(ChatEventType.CHAT_MESSAGE_RECEIVED, (ChatEvent payload) -> {
    ChatMessageReceivedEvent chatMessageReceivedEvent = (ChatMessageReceivedEvent) payload;
    // You code to handle chatMessageReceived event
    
});

Importante

Problema conhecido: durante o uso conjunto do SDK de Chat e de Chamada do Android no mesmo aplicativo, o recurso de notificações em tempo real do SDK de Chat não funciona. Você poderá receber um problema de resolução de dependência. Enquanto trabalhamos em uma solução, desative o recurso de notificações em tempo real adicionando as informações a seguir de dependência ao arquivo build.gradle do aplicativo e sonde a API GetMessages para exibir as mensagens de entrada para os usuários.

implementation ("com.azure.android:azure-communication-chat:1.0.0") {
    exclude group: 'com.microsoft', module: 'trouter-client-android'
}
implementation 'com.azure.android:azure-communication-calling:1.0.0'

Observe, com a atualização acima, que se o aplicativo tentar acessar qualquer API de notificação como chatAsyncClient.startRealtimeNotifications() ou chatAsyncClient.addEventHandler(), haverá um erro de runtime.

Notificações por push

Confira as notificações por push do Android para obter detalhes.

Adicionar um usuário como participante ao thread de chat

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

// 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 os usuários em um thread

Substitua o comentário <LIST USERS> 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 um usuário de uma conversa de chat

Removeremos o segundo usuário da conversa agora.

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

// 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 seguinte código:

chatThreadAsyncClient.sendTypingNotification().get();

Enviar uma confirmação de leitura

Enviaremos a confirmação de leitura para a mensagem enviada acima.

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

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Listar confirmações de leitura

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

// 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 exibir a saída do código e a saída do agente do ChatClient.

Exemplo de código

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

Pré-requisitos

Antes de começar, é preciso:

Configurando

Criar um aplicativo em C#

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

dotnet new console -o ChatQuickstart

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

cd ChatQuickstart
dotnet build

Instalar o pacote

Instalar o SDK de 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 Essa classe é necessária para a funcionalidade de chat. Crie uma instância dela com suas informações de assinatura e use-a para criar, obter e excluir conversas.
ChatThreadClient Essa classe é necessária para a funcionalidade de conversa de chat. Obtenha uma instância por meio de ChatClient e use-a para enviar/receber/atualizar/excluir mensagens, adicionar/remover/obter participantes e enviar notificações de digitação e confirmações de leitura.

Criar um cliente de chat

Para criar um cliente de chat, você usará o 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 classe CommunicationIdentityClient do SDK de Identidade para criar um usuário e emitir um token a ser passado para o cliente de chat.

Saiba mais sobre os tokens de acesso do usuário.

Este início rápido não abrange a criação de uma camada de serviço para gerenciar tokens relacionados ao aplicativo de chat, embora isso seja recomendado. Saiba mais sobre a Arquitetura de Chat

Copie os seguintes snippets de código e cole-os no arquivo de origem: Program.cs

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Azure Communication service endpoint
            Uri endpoint = new Uri("<replace with your resource endpoint>");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Iniciar uma conversa de chat

Use o método createChatThread no chatClient para criar uma conversa de chat.

  • Use topic para fornecer um tópico a esse chat; o tópico pode ser atualizado depois que a conversa de chat é criada por meio da função UpdateTopic.
  • Use a propriedade participants para passar uma lista de objetos ChatParticipant a serem adicionados ao thread de chat. O objeto ChatParticipant é inicializado com um objeto CommunicationIdentifier. CommunicationIdentifier poderia ser do tipo CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier ou PhoneNumberIdentifier. Por exemplo, para obter um objeto CommunicationIdentifier, é necessário transmitir uma ID de acesso que tenha sido criada seguindo as instruções em Criar um usuário

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

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

O método GetChatThreadClient retorna um cliente de conversa para uma conversa que já existe. Ele pode ser usado para executar operações na conversa criada: adicionar membros, enviar mensagens etc. threadId é a ID exclusiva da conversa de chat existente.

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

Listar todas as conversas de chat

Use GetChatThreads para recuperar todas as conversas de chat das 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 uma conversa de chat

Use SendMessage para enviar uma mensagem para uma conversa.

  • Use content para fornecer o conteúdo da mensagem, que é obrigatório.
  • Use type para o tipo de conteúdo da mensagem, como "Text" ou "HTML". Se não for especificado, a opção "Text" será a usada.
  • Use senderDisplayName para especificar o nome de exibição do remetente. Se não for especificado, uma cadeia de caracteres vazia será a usada.
  • Use metadata opcionalmente para incluir dados adicionais que você queira 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 caso de uso específico. Por exemplo, ao compartilhar um link de arquivo na mensagem, pode ser interessante adicionar "hasAttachment:true" nos metadados para que o aplicativo do destinatário possa analisá-la e exibi-la de acordo.
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 de uma conversa de chat

Você pode recuperar mensagens de chat sondando o método GetMessages no cliente da conversa de chat 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 DateTimeOffset opcional. Se esse deslocamento for especificado, você receberá mensagens que foram recebidas, atualizadas ou excluídas depois dele. Observe que as mensagens recebidas antes da hora de deslocamento, mas editadas ou removidas depois dela, também serão retornadas.

GetMessages retorna a última versão da mensagem, incluindo as edições ou as exclusões que ocorreram na mensagem usando UpdateMessage e DeleteMessage. Para mensagens excluídas, chatMessage.DeletedOn retorna um valor datetime que indica quando a mensagem foi excluída. Para as mensagens editadas, chatMessage.EditedOn retorna um datetime indicando quando a mensagem foi editada. A hora original da criação da mensagem pode ser acessada usando chatMessage.CreatedOn e pode ser usada para ordenar as mensagens.

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

  • Text: mensagem de chat normal enviada por um membro da conversa.

  • Html: uma mensagem de texto formatada. Observe que os usuários dos Serviços de Comunicação não podem enviar mensagens RichText no momento. Há suporte para esse tipo de mensagem nas mensagens enviadas de usuários do Teams para os usuários dos Serviços de Comunicação em cenários de interoperabilidade do Teams.

  • TopicUpdated: mensagem do sistema que indica que o tópico foi atualizado. (readonly)

  • ParticipantAdded: mensagem do sistema que indica que um ou mais participantes foram adicionados à conversa do chat.(readonly)

  • ParticipantRemoved: mensagem do sistema que indica que um participante foi removido do thread de chat.

Para obter mais detalhes, confira Tipos de mensagem.

Adicionar um usuário como participante ao thread de chat

Depois que uma conversa é criada, você pode adicionar e remover usuários dela. Quando você adiciona usuários, você concede a eles acesso para poderem enviar mensagens para a conversa e adicionar/remover outro participante. Para chamar AddParticipants, verifique se você adquiriu um novo token de acesso e uma identidade para esse usuário. O usuário precisará desse token de acesso para inicializar o cliente de chat.

Use AddParticipants para adicionar um ou mais participantes à conversa de chat. A seguir, estão os atributos com suporte para participantes de cada conversa:

  • communicationUser, obrigatório, é a identidade do participante da conversa.
  • displayName, opcional, é o nome de exibição do participante do thread.
  • shareHistoryTime, opcional, é o horário no qual o histórico do chat é compartilhado 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 conversa

Use GetParticipants para recuperar os participantes da conversa de chat.

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

Enviar confirmação de leitura

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

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Executar o código

Execute o aplicativo do seu diretório de aplicativo com o comando dotnet run.

dotnet run

Exemplo de código

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

Pré-requisitos

Antes de começar, é preciso:

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

  • Instale o Xcode e o CocoaPods. Você usa o Xcode a fim de criar um aplicativo iOS para o início rápido e o CocoaPods para instalar as dependências.

  • Criar um recurso dos Serviços de Comunicação do Azure. Para obter detalhes, confira Início Rápido: criar e gerenciar recursos dos Serviços de Comunicação. Você precisará registrar o ponto de extremidade e a cadeia de conexão do recurso para este guia de início rápido.

  • Crie dois usuários nos Serviços de Comunicação do Azure e emita para eles um Token de Acesso do Usuário. Defina o escopo como chat e anote a cadeia de caracteres do token, bem como a cadeia de caracteres da user_id. Neste início rápido, você criará uma conversa com um participante inicial e depois adicionará um segundo participante a ela. Você também pode usar a CLI do Azure e executar o comando abaixo com a 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, confira Usar a CLI do Azure para criar e gerenciar tokens de acesso.

Configurando

Criar um aplicativo iOS

Abra o Xcode e selecione Crie um novo projeto Xcode. Em seguida, selecione iOS como a plataforma e Aplicativo como o modelo.

Em nome do projeto, insira ChatQuickstart. Em seguida, selecione Storyboard como a interface, Representante de Aplicativo UIKit como o ciclo de vida e Swift como a linguagem.

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

Instalar as bibliotecas

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

Por meio da linha de comando, acesse o diretório raiz do projeto iOS ChatQuickstart. Crie um Podfile com o seguinte comando: pod init.

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

pod 'AzureCommunicationChat', '~> 1.3.6'

Instale as dependências com o seguinte comando: pod install. Observe que isso também cria um workspace do Xcode.

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

Configurar os espaços reservados

Abra o workspace ChatQuickstart.xcworkspace no Xcode e depois abra ViewController.swift.

Neste início rápido, você adicionará o seu código em viewController e verá a saída no console do Xcode. Este início rápido não aborda a criação de uma interface do usuário no iOS.

Na parte superior de viewController.swift, importe as bibliotecas AzureCommunication e AzureCommunicationChat:

import AzureCommunicationCommon
import AzureCommunicationChat

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

override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.

        let semaphore = DispatchSemaphore(value: 0)
        DispatchQueue.global(qos: .background).async {
            do {
                // <CREATE A CHAT CLIENT>
                
                // <CREATE A CHAT THREAD>

                // <LIST ALL CHAT THREADS>

                // <GET A CHAT THREAD CLIENT>

                // <SEND A MESSAGE>

                // <SEND A READ RECEIPT >

                // <RECEIVE MESSAGES>

                // <ADD A USER>
                
                // <LIST USERS>
            } catch {
                print("Quickstart failed: \(error.localizedDescription)")
            }
        }
    }

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

Criar um cliente de chat

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

Saiba mais sobre os tokens de acesso do usuário.

Este início rápido não abrange a criação de uma camada de serviço para gerenciar tokens relacionados ao aplicativo de chat, embora isso seja recomendado. Saiba mais sobre a Arquitetura de Chat

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

let endpoint = "<ACS_RESOURCE_ENDPOINT>"
let credential =
try CommunicationTokenCredential(
    token: "<ACCESS_TOKEN>"
)
let options = AzureCommunicationChatClientOptions()

let chatClient = try ChatClient(
    endpoint: endpoint,
    credential: credential,
    withOptions: options
)

Substitua <ACS_RESOURCE_ENDPOINT> pelo ponto de extremidade do 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 as 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 Essa classe é necessária para a funcionalidade de chat. Crie uma instância dela com suas informações de assinatura e use-a para criar, obter, excluir threads e assinar eventos de chat.
ChatThreadClient Essa classe é necessária para a funcionalidade de conversa de chat. Você obtém uma instância por meio do ChatClient e a usa para enviar, receber, atualizar ou excluir mensagens. Você também pode usá-la para adicionar, remover e obter usuários, enviar notificações de digitação e confirmações de leitura.

Iniciar uma conversa de chat

CreateChatThreadResult é a resposta retornada pela criação de um thread de chat. Ele contém uma propriedadechatThread que é o objetoChatThreadProperties. Este objeto contém o threadId que pode ser usado para obter ChatThreadClient operações de execução no thread criado: Adicionar participantes, enviar mensagem, etc.

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

let request = CreateChatThreadRequest(
    topic: "Quickstart",
    participants: [
        ChatParticipant(
            id: CommunicationUserIdentifier("<USER_ID>"),
            displayName: "Jack"
        )
    ]
)

var threadId: String?
chatClient.create(thread: request) { result, _ in
    switch result {
    case let .success(result):
        threadId = result.chatThread?.id

    case .failure:
        fatalError("Failed to create thread.")
    }
    semaphore.signal()
}
semaphore.wait()

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

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

Listar todas as conversas de chat

Depois de criar uma conversa de chat, podemos listar todas as conversas de chat chamando o método listChatThreads em ChatClient. Substitua o comentário <LIST ALL CHAT THREADS> pelo código a seguir:

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 conversa de chat

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

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

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

Enviar uma mensagem para uma conversa de chat

Use o método send para enviar uma mensagem a uma conversa identificada por threadId.

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

  • Use content para fornecer o conteúdo da mensagem de chat
  • 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 dados adicionais que você queira 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 caso de uso específico. Por exemplo, ao compartilhar um link de arquivo na mensagem, pode ser interessante adicionar "hasAttachment:true" nos metadados para que o aplicativo do destinatário possa analisá-la e exibi-la de acordo.

SendChatMessageResult é a resposta retornada do envio de uma mensagem; ela contém uma ID, que é a ID exclusiva da mensagem.

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

let message = SendChatMessageRequest(
                        content: "Hello!",
                        senderDisplayName: "Jack",
                        type: .text,
                        metadata: [
                            "hasAttachment": "true",
                            "attachmentUrl": "https://contoso.com/files/attachment.docx"
                        ]
                    )

var messageId: String?

chatThreadClient.send(message: message) { result, _ in
    switch result {
    case let .success(result):
        print("Message sent, message id: \(result.id)")
        messageId = result.id
    case .failure:
        print("Failed to send message")
    }
    semaphore.signal()
}
semaphore.wait()

Enviar uma confirmação de leitura

Use o método sendReadReceipt para postar um evento de confirmação de leitura em um thread de chat, em nome de um usuário. messageId é a ID exclusiva da mensagem de chat lida.

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

if let id = messageId {
    chatThreadClient.sendReadReceipt(forMessage: id) { result, _ in
        switch result {
        case .success:
            print("Read receipt sent")
        case .failure:
            print("Failed to send read receipt")
        }
        semaphore.signal()
    }
    semaphore.wait()
} else {
    print("Cannot send read receipt without a message id")
}

Receber mensagens de chat de uma conversa de chat

Com a sinalização em tempo real, você pode criar assinaturas para escutar as novas mensagens de entrada 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 abaixo. Depois de habilitar 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 chat sondando o método listMessages em intervalos especificados. Veja o seguinte snippet 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 thread de chat

Depois que uma conversa é criada, você pode adicionar e remover usuários dela. Quando você adiciona usuários, você concede a eles acesso para poderem enviar mensagens para a conversa e adicionar/remover outro participante. Para chamar add, verifique se você adquiriu um novo token de acesso e uma identidade para esse usuário. O usuário precisará desse token de acesso para inicializar o cliente de chat.

Use o add método deChatThreadClient para adicionar um ou mais participantes à conversa de chat. A seguir, estão os atributos com suporte para participantes de cada conversa:

  • id, obrigatório, é a identidade do participante da conversa.
  • displayName, opcional, é o nome de exibição do participante do thread.
  • shareHistoryTime, opcional, é o horário no qual o histórico do chat é compartilhado com o participante.

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

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> pela ID de usuário dos Serviços de Comunicação do usuário a ser adicionado.

Listar os usuários em um thread

Use o listParticipants método para obter todos os participantes de uma conversa de chat específica.

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

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

As notificações por push alertam clientes sobre mensagens de entrada em uma thread de chat em situações em que o aplicativo móvel não está sendo executado no primeiro plano. Atualmente, o envio de notificações por chat por push com o Hub de Notificação só tem suporte para SDK do IOS na versão 1.3.0. Consulte o artigo Habilitar Notificação por Push em seu aplicativo de chat para obter detalhes.

Executar o código

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

Observação: Defina Build Settings > Build Options > Enable Bitcode como No. No momento, o SDK do AzureCommunicationChat para iOS não permite habilitar o bitcode, o problema do GitHub a seguir está acompanhando essa situação.

Exemplo de código

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

Pré-requisitos

Criar usuário

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

Para adicionar uma nova etapa no 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, em seguida, selecione Adicionar uma ação.

  2. Na caixa de pesquisa Escolher uma operação, insira a Identidade dos Serviços de Comunicação. Na lista de ações, selecione Criar um usuário.

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

  3. Insira a cadeia de conexão. Para obter a URL da cadeia de conexão no portal do Azure, vá para o recurso Serviços de Comunicação do Azure. No menu de recursos, selecione Chaves e, em seguida, selecione Cadeia de conexão. Selecione o ícone de cópia para copiar a cadeia de conexão primária.

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

  4. Insira um nome para a conexão.

  5. Selecione Mostrar opções avançadas e, em seguida, selecione o escopo do token. A ação fera um token de acesso e o tempo de expiração com o escopo especificado. Essa ação também gera uma 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, opções de ação Criar usuário.

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

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

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

Crie uma conversa de chat

  1. Adicione uma nova ação.

  2. Na caixa de pesquisa Escolher uma operação, insira o Chat dos Serviços de Comunicação. Na lista de ações, selecione Criar uma conversa de chat.

    Captura de tela que mostra o conector de Chat dos Serviços de Comunicação do Azure, ação de thread Criar um chat.

  3. Insira a URL do ponto de extremidade dos Serviços de Comunicação. Para obter a URL do ponto de extremidade no portal do Azure, vá para o recurso Serviços de Comunicação do Azure. No menu de recursos, selecione Chaves e, em seguida, selecione Ponto de extremidade.

  4. Insira um nome para a conexão.

  5. Selecione o token de acesso gerado na seção anterior e adicione uma descrição do tópico da conversa de chat. Adicione o usuário criado e insira um nome para o participante.

    Captura de tela que mostra o diálogo da ação de Criar uma conversa de chat do conector de Chat dos Serviços de Comunicação do Azure.

Enviar uma mensagem

  1. Adicione uma nova ação.

  2. Na caixa de pesquisa Escolher uma operação, insira o Chat dos Serviços de Comunicação. Na lista de ações, selecione Enviar uma mensagem para a conversa de chat.

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

  3. Insira o token de acesso, a ID da conversa, o conteúdo e o nome.

    Captura de tela que mostra o diálogo da ação de Enviar uma mensagem de chat do conector de Chat dos Serviços de Comunicação do Azure.

Lieste as mensagens de thread de chat

Para verificar se você enviou uma mensagem corretamente:

  1. Adicione uma nova ação.

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

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

  3. Insira o token de acesso e a ID da conversa.

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

Como testar o seu aplicativo lógico

Para executar manualmente o fluxo de trabalho, selecione Executar na barra de ferramentas do designer. 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, confira Como executar seu fluxo de trabalho.

Agora, selecione Listar mensagens da conversa de chat. Nas saídas da ação, verifique a mensagem que foi enviada.

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

Limpar os recursos do fluxo de trabalho

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

Limpar os recursos

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, exclua o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele. Saiba mais sobre como limpar recursos.

Próximas etapas

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

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

Experimente o aplicativo Chat Hero

Você também pode querer: