Compartir vía

Inicio rápido: Incorporación de chat a una aplicación

  • Artículo

Comience a usar Azure Communication Services mediante el SDK de chat de Communication Services para agregar chat en tiempo real a la aplicación. En esta guía de inicio rápido, usaremos el SDK de chat para crear conversaciones de chat que permitan a los usuarios mantener conversaciones entre sí. Para obtener más información acerca de los conceptos de chat, visite la documentación conceptual de chat.

Requisitos previos

  • Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

  • Un recurso activo de Communication Services y una cadena de conexión. Cree un recurso de Communication Services.

  • Instale la CLI de Azure.

  • Tenga en cuenta el punto de conexión de recursos de Communication Services. Puede obtener el punto de conexión de Azure Portal. Como alternativa, puede encontrar la dirección URL del punto de conexión en la cadena de conexión. Es la dirección URL que viene después de endpoint= y comienza por https://.

  • Un Token de acceso de usuario. Asegúrese de establecer el ámbito en chat y anote la cadena del token, así como la cadena user_Id. También puede usar la CLI de Azure y ejecutar el comando siguiente con la cadena de conexión para crear un usuario y un token de acceso.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    Para más información, consulte Uso de la CLI de Azure para crear y administrar tokens de acceso.

Instalación

Adición de la extensión

Agregue la extensión Azure Communication Services para la CLI de Azure mediante el comando az extension.

az extension add --name communication

Inicio de sesión en la CLI de Azure

Deberá iniciar sesión en la CLI de Azure. Para iniciar sesión, ejecute el comando az login desde el terminal y proporcione sus credenciales.

(Opcional) Uso de operaciones de identidad de la CLI de Azure sin pasar una cadena de conexión o un token de acceso

Almacenamiento del punto de conexión en una variable de entorno

Puede configurar la variable de entorno AZURE_COMMUNICATION_ENDPOINT para usar operaciones de chat de la CLI de Azure sin tener que usar --endpoint para pasar la cadena de conexión. Para configurar una variable de entorno, abra una ventana de consola y seleccione el sistema operativo en las pestañas siguientes. Reemplace <yourEndpoint> por el punto de conexión real.

Abra una ventana de consola y escriba el siguiente comando:

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

Después de agregar la variable de entorno, puede que tenga que reiniciar todos los programas en ejecución que necesiten leer la variable de entorno, incluida la ventana de consola. Por ejemplo, si usa Visual Studio como editor, reinícielo antes de ejecutar el ejemplo.

Almacenamiento del token de acceso en una variable de entorno

Puede configurar la variable de entorno AZURE_COMMUNICATION_ACCESS_TOKEN para usar operaciones de chat de la CLI de Azure sin tener que usar --access-token para pasar el token de acceso. Para configurar una variable de entorno, abra una ventana de consola y seleccione el sistema operativo en las pestañas siguientes. Reemplace <yourAccessToken> con su token de acceso real.

Abra una ventana de consola y escriba el siguiente comando:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Después de agregar la variable de entorno, puede que tenga que reiniciar todos los programas en ejecución que necesiten leer la variable de entorno, incluida la ventana de consola. Por ejemplo, si usa Visual Studio como editor, reinícielo antes de ejecutar el ejemplo.

Operaciones

Inicio de un subproceso de chat

Utilice el comando thread create para crear un subproceso de chat.

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

Si ha almacenado el punto de conexión y el token de acceso en variables de entorno como se indicó anteriormente, no tendrá que pasarlos al comando.

az communication chat thread create --topic "<chatTopic>"
  • Use <chatTopic> para proporcionar un tema a la conversación. Puede actualizar el tema después de crear la conversación de chat mediante el comando thread update-topic.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Actualizar el tema de una conversación de chat

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"
  • Reemplace <chatThreadId> por el identificador del subproceso de chat.
  • Reemplace <chatTopic> por el nuevo tema de chat que desea establecer.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Lista de todas las conversaciones de chat

El comando thread list devuelve la lista de subprocesos de chat de un usuario.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • De manera opcional, utilice <startTime> para especificar el primer momento a partir del cual obtener las conversaciones de chat.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Envío de un mensaje a un subproceso de chat

Utilice el comando message send para enviar un mensaje a una conversación de chat que ha creado, identificada mediante threadId.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"
  • Reemplace <chatThreadId> por el identificador del subproceso de chat.
  • Utilice <content> para proporcionar el contenido del mensaje de chat.
  • Utilice <messageType> para especificar el tipo de contenido del mensaje. Los valores posibles son text y html. Si no especifica un valor, el valor predeterminado es text.
  • De manera opcional, utilice <displayName> para especificar el nombre para mostrar del remitente.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Enumere los mensajes de chat de un subproceso de chat

El comando message list devuelve la lista de mensajes de chat en un subproceso de chat.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Reemplace <chatThreadId> por el identificador del subproceso de chat.
  • De manera opcional, utilice <startTime> para especificar el primer momento a partir del cual obtener las conversaciones de chat.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Recepción de un mensaje de chat de un subproceso de chat

Puede recuperar mensajes de chat mediante el comando message list.

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Reemplace <chatThreadId> por el identificador del subproceso de chat.
  • Reemplace <messageId> por el id. del mensaje que le gustaría recuperar.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Envío de confirmación de lectura

Puede usar el comando message receipt send para publicar un evento de confirmación de lectura en una conversación de chat en nombre de un usuario.

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Reemplace <chatThreadId> por el identificador del subproceso de chat.
  • Reemplace <messageId> para especificar el identificador del último mensaje leído por el usuario actual.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Adición de un usuario como miembro a la conversación del chat

Una vez que se crea una conversación de chat, puede agregar y quitar usuarios de ella. Al agregar usuarios, les concede acceso para enviar mensajes a la conversación de chat y para agregar o quitar otros participantes. Antes de llamar al comando participant add, asegúrese de que ha adquirido un nuevo token de acceso y una identidad para el usuario.

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Reemplace <chatThreadId> por el identificador del subproceso de chat.
  • Reemplace <userId> por su userId.
  • De manera opcional, utilice <displayName> para especificar el nombre para mostrar del remitente.
  • De manera opcional, utilice <startTime> para especificar el primer momento a partir del cual obtener las conversaciones de chat.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Enumeración de los participantes en una conversación de un chat

En una conversación, los participantes se pueden enumerar de forma similar a como se agregan.

Use el comando participant list para recuperar los participantes de la conversación.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"
  • Reemplace <chatThreadId> por el identificador del subproceso de chat.
  • De manera opcional, use <skip> para omitir los participantes hasta una posición especificada en la respuesta.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Eliminación del participante de una conversación de chat

Puede quitar un participante de chat de un subproceso de chat mediante el comando "quitar participante".

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"
  • Reemplace <chatThreadId> por el identificador del subproceso de chat.
  • Reemplace <userId> por el Id. de usuario que desea quitar del subproceso de chat.
  • Reemplace <endpoint> por el punto de conexión de Azure Communication Services.
  • Reemplace <token> por el token de acceso obtenido anteriormente mediante el comando en ejecución identity token issue.

Requisitos previos

Antes de comenzar, compruebe lo siguiente:

  • Cree de una cuenta de Azure con una suscripción activa. Para más información, consulte Creación de una cuenta gratuita.

  • Instale las versiones Active LTS y Maintenance LTS de Node.js.

  • Cree un recurso de Azure Communication Services. Para más información, consulte Creación de un recurso de Azure Communication Services. Deberá registrar la cadena de conexión y del punto de conexión del recurso para esta guía de inicio rápido.

  • Cree tres usuarios de Communication Services y emítales Token de acceso de usuario. Asegúrese de establecer el ámbito en chat y anote la cadena del token, así como la cadena user_Id. La demo completa crea una conversación con dos participantes iniciales y, después, agrega un tercer participante a la misma. También puede usar la CLI de Azure y ejecutar el comando siguiente con la cadena de conexión para crear un usuario y un token de acceso.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    Para más información, consulte Uso de la CLI de Azure para crear y administrar tokens de acceso.

Instalación

Creación de una nueva aplicación web

En primer lugar, abra la ventana de comandos o de terminal, cree un nuevo directorio para la aplicación y navegue hasta este.

mkdir chat-quickstart && cd chat-quickstart

Ejecute npm init -y para crear un archivo package.json con la configuración predeterminada.

npm init -y

Instalación de los paquetes

Use el comando npm install para instalar los siguientes SDK de Communication Services para JavaScript.

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

La opción --save muestra la biblioteca como dependencia en el archivo package.json.

Instalación del marco de la aplicación

En esta guía de inicio rápido se usa parcel para agrupar los recursos de la aplicación. Ejecute el siguiente comando para llevar a cabo la instalación y que se muestre como una dependencia de desarrollo en package.json:

npm install parcel --save-dev

Cree un archivo index.html en el directorio raíz del proyecto. Usaremos este archivo como plantilla para agregar la funcionalidad de chat mediante Chat SDK de Azure Communication Services 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>

Cree un archivo en el directorio raíz del proyecto denominado client.js que contendrá la lógica de la aplicación para esta guía de inicio rápido.

Creación de un cliente de chat

Para crear un cliente de chat en una aplicación web, usará el punto de conexión de Communication Services y el token de acceso que se generó como parte de los pasos de los requisitos previos.

Los tokens de acceso de usuario permiten compilar aplicaciones cliente que se autentiquen directamente en Azure Communication Services. En este inicio rápido no se trata la creación de un nivel de servicio para administrar tokens para una aplicación de chat. Consulte Conceptos de chat para más información sobre la arquitectura de chat y Tokens de acceso de usuario para más información sobre los tokens de acceso.

En client.js, use el punto de conexión y el token de acceso del código siguiente para agregar la funcionalidad de chat mediante Chat SDK de Azure Communication Services 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!');

Ejecución del código

Ejecute el siguiente comando para ejecutar la aplicación:

npx parcel index.html

Abra el explorador web y vaya a http://localhost:1234/. En la consola de herramientas de desarrollo en el explorador, debe ver lo siguiente:

Azure Communication Chat client created!

Modelo de objetos

Las siguientes clases e interfaces controlan algunas de las características principales de Chat SDK de Azure Communication Services para JavaScript.

Nombre Descripción
ChatClient Esta clase es necesaria para la funcionalidad de chat. Cree una instancia de ella con la información de la suscripción y úsela para crear, obtener y eliminar conversaciones, y para suscribirse a eventos de chat.
ChatThreadClient Esta clase es necesaria para la funcionalidad de subproceso de chat. Obtiene una instancia de a través de la clase ChatClient y la usa para enviar, recibir, actualizar o eliminar mensajes, agregar, quitar u obtener usuarios, enviar notificaciones de escritura y confirmaciones de lectura.

Inicio de un subproceso de chat

Use el método createThread para crear un subproceso de chat.

createThreadRequest se usa para describir la solicitud de subproceso:

  • Utilice topic para proporcionar un tema a este chat. Los temas se pueden actualizar después de crear el subproceso de chat mediante la función UpdateThread.
  • Use participants para enumerar los participantes que se van a agregar a la conversación del chat.

Cuando se resuelve, el método createChatThread devuelve CreateChatThreadResult. Este modelo contiene una propiedad chatThread donde se puede acceder al id del subproceso recién creado. Luego, se puede utilizar id para obtener una instancia de ChatThreadClient. A continuación, se puede usar ChatThreadClient para realizar una operación dentro del subproceso, como enviar mensajes o enumerar 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>
  });

Al actualizar la pestaña del explorador, debería ver lo siguiente en la consola:

Thread created: <thread_id>

Obtención de un cliente de subproceso de chat

El método getChatThreadClient devuelve un chatThreadClient para un subproceso que ya existe. Se puede usar para realizar operaciones en el subproceso creado: agregar participantes, enviar un mensaje, etc. threadId es el identificador único de la conversación del chat existente.

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

Agregue este código en lugar del comentario <CREATE CHAT THREAD CLIENT> en client.js, actualice la pestaña del explorador y compruebe la consola. Debería ver lo siguiente:

Chat Thread client for threadId: <threadId>

Lista de todas las conversaciones de chat

El método listChatThreads devuelve un PagedAsyncIterableIterator de tipo ChatThreadItem. Se puede usar para enumerar todas las conversaciones de chat. Un iterador de [ChatThreadItem] es la respuesta que devuelven los subprocesos de lista.

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

Envío de un mensaje a un subproceso de chat

Utilice el método sendMessage para enviar un mensaje a un subproceso identificado mediante threadId.

sendMessageRequest se utiliza para describir la solicitud del mensaje:

  • Utilice content para proporcionar el contenido del mensaje de chat.

sendMessageOptions se usa para describir los parámetros opcionales de la operación:

  • Utilice senderDisplayName para especificar el nombre para mostrar del remitente.
  • Use type para especificar el tipo de mensaje, como "texto" o "html".
  • Opcionalmente, use metadata para incluir otros datos que quiera enviar con el mensaje. Este campo proporciona un mecanismo para que los desarrolladores amplíen la funcionalidad de los mensajes de chat y agreguen información personalizada para su caso de uso. Por ejemplo, al compartir un vínculo de archivo en el mensaje, es posible que quiera agregar "hasAttachment: true" en los metadatos para que la aplicación del destinatario pueda analizarlo y mostrarlo en consecuencia.

SendChatMessageResult es la respuesta que se devuelve al enviar un mensaje. Contiene un identificador que es el identificador único del mensaje.

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

Agregue este código en lugar del comentario <SEND MESSAGE TO A CHAT THREAD> en el archivo client.js, actualice la pestaña del explorador y compruebe la consola.

Message sent!, message id:<number>

Recepción de mensajes de chat de un subproceso de chat

Con la señalización en tiempo real, puede suscribirse para escuchar nuevos mensajes entrantes y actualizar los mensajes actuales en la memoria en consecuencia. Azure Communication Services admite una lista de eventos a los que se puede suscribir.

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

Agregue este código en lugar del comentario <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> en client.js. Actualice la pestaña del explorador; debería ver en la consola un mensaje Notification chatMessageReceived.

También puede recuperar mensajes de chat mediante el sondeo del método listMessages a intervalos especificados.


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

Agregue este código en lugar del comentario <LIST MESSAGES IN A CHAT THREAD> en client.js. Actualice la pestaña; en la consola debería encontrar la lista de los mensajes enviados en esta conversación del chat.

listMessages devuelve distintos tipos de mensajes que se pueden identificar mediante chatMessage.type.

Para obtener más información, consulte Tipos de mensajes.

Adición de un usuario como miembro a la conversación del chat

Una vez que se crea un subproceso de chat, puede agregar y quitar usuarios de este. Al agregar usuarios, les concede acceso para enviar mensajes a la conversación del chat, y agregar o quitar otros participantes.

Antes de llamar al método addParticipants, asegúrese de que ha adquirido un nuevo token de acceso y una identidad para el usuario. El usuario necesitará ese token de acceso para poder inicializar su cliente de chat.

addParticipantsRequest describe el objeto de solicitud, donde participants enumera los participantes que se van a agregar a la conversación del chat.

  • El elemento id obligatorio es el identificador de la comunicación que se va a agregar al subproceso de chat.
  • displayName es opcional y es el nombre para mostrar del participante de la conversación.
  • shareHistoryTime es opcional y es la hora a partir de la cual el historial de chat se compartió con el participante. Para compartir el historial desde el inicio del subproceso de chat, establezca esta propiedad en cualquier fecha igual o anterior a la hora de creación del subproceso. Para no compartir ningún historial anterior a la hora en que se agregó el participante, establézcala en la fecha actual. Para compartir el historial parcialmente, establezca la opción en la fecha de su elección.

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

await chatThreadClient.addParticipants(addParticipantsRequest);

Reemplace NEW_PARTICIPANT_USER_ID_USER_ID por un identificador de usuario nuevo. Agregue este código en lugar del comentario <ADD NEW PARTICIPANT TO THREAD> en client.js

Enumeración de usuarios en un subproceso de chat

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

Agregue este código en lugar del comentario <LIST PARTICIPANTS IN A THREAD> en client.js, actualice la pestaña del explorador y compruebe la consola; debería ver información acerca de los usuarios de un subproceso.

Eliminación de un usuario de un subproceso de chat

En una conversación del chat, los participantes se pueden eliminar de forma similar a como se agregan. Para quitarlos, será preciso realizar un seguimiento de los identificadores de los participantes que se han agregado.

Utilice el método removeParticipant, donde participant es el usuario de la comunicación que se va a quitar del subproceso.


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

Reemplace PARTICIPANT_ID por un id. de usuario utilizado en el paso anterior (). Agregue este código en lugar del comentario <REMOVE PARTICIPANT FROM THREAD> en client.js.

Suscripción al estado de conexión de las notificaciones en tiempo real

La suscripción a eventos realTimeNotificationConnected y realTimeNotificationDisconnected permite saber cuándo está activa la conexión al servidor de llamadas.

// subscribe to realTimeNotificationConnected event
chatClient.on('realTimeNotificationConnected', () => {
  console.log("Real time notification is now connected!");
  // your code here
});
// subscribe to realTimeNotificationDisconnected event
chatClient.on('realTimeNotificationDisconnected', () => {
  console.log("Real time notification is now disconnected!");
  // your code here
});

Código de ejemplo

Busque el código finalizado de este inicio rápido en GitHub.

Requisitos previos

Antes de comenzar, compruebe lo siguiente:

Instalación

Creación de una nueva aplicación de Python

Abra la ventana de comandos o el terminal, cree un nuevo directorio para la aplicación y vaya hasta él.

mkdir chat-quickstart && cd chat-quickstart

Use un editor de texto para crear un archivo llamado start-chat.py en el directorio raíz del proyecto. Agregue la estructura del programa, incluido un control de excepciones básico. En las secciones siguientes agregará todo el código fuente de esta guía de inicio rápido a este archivo.

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)

Instalación del SDK

Use el siguiente comando para instalar el SDK:


pip install azure-communication-chat

Modelo de objetos

Las siguientes clases e interfaces controlan algunas de las características principales de Chat SDK de Azure Communication Services para Python.

Nombre Descripción
ChatClient Esta clase es necesaria para la funcionalidad de chat. Cree una instancia de esta con la información de suscripción y úsela para crear, obtener y eliminar conversaciones.
ChatThreadClient Esta clase es necesaria para la funcionalidad de conversación de chat. Obtenga una instancia mediante ChatClient y úsela para enviar, recibir, actualizar y eliminar mensajes. También puede usarla para agregar, quitar y obtener usuarios, o enviar notificaciones de escritura y confirmaciones de lectura.

Creación de un cliente de chat

Para crear un cliente de chat, usará el punto de conexión de Communication Services y el token de acceso que se generó como parte de los pasos de requisitos previos.

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

En este inicio rápido no se aborda la creación de un nivel de servicio para administrar tokens para la aplicación de chat, aunque se recomienda. Para más información, consulte la sección "Arquitectura del chat" de Conceptos de chat.

Inicio de un subproceso de chat

Use el método create_chat_thread para crear un subproceso de chat.

  • Use topic para proporcionar un tema a la conversación. Puede actualizar el tema después de crear la conversación de chat mediante la función update_thread.
  • Use thread_participants para enumerar los elementos ChatParticipant que se van a agregar a la conversación de chat. ChatParticipant toma el tipo CommunicationUserIdentifier como un elemento user.

CreateChatThreadResult es el resultado devuelto por la creación de una conversación. Puede utilizarlo para capturar el elemento id de la conversación de chat que se ha creado. A continuación, se puede utilizar el valor de id para capturar un objeto ChatThreadClient mediante el método get_chat_thread_client. Se puede usar ChatThreadClient para realizar otras operaciones de chat en esta conversación 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)

Obtención de un cliente de subproceso de chat

El método get_chat_thread_client devuelve un cliente de subproceso para un subproceso que ya existe. Lo puede utilizar para realizar operaciones en la conversación creada. Por ejemplo, puede agregar participantes y enviar mensajes. thread_id es el identificador único de la conversación de chat existente.

Se puede usar ChatThreadClient para realizar otras operaciones de chat en esta conversación de chat.

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

Lista de todas las conversaciones de chat

El método list_chat_threads devuelve un iterador de tipo ChatThreadItem.

  • Utilice start_time para especificar el primer punto en el tiempo a partir del cual obtener las conversaciones de chat.
  • Utilice results_per_page para especificar el número máximo de conversaciones de chat que se devuelven por página.

La enumeración de conversaciones devuelve como respuesta un iterador de [ChatThreadItem].

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)

Envío de un mensaje a un subproceso de chat

Utilice el método send_message para enviar un mensaje a una conversación de chat recién creada, identificada mediante thread_id.

  • Utilice content para proporcionar el contenido del mensaje de chat.
  • Utilice chat_message_type para especificar el tipo de contenido del mensaje. Los valores posibles son text y html. Si no especifica un valor, el valor predeterminado es text.
  • Utilice sender_display_name para especificar el nombre para mostrar del remitente.
  • Opcionalmente, use metadata para incluir los datos adicionales que quiera enviar con el mensaje. Este campo proporciona un mecanismo para que los desarrolladores amplíen la funcionalidad de los mensajes de chat y agreguen información personalizada para su caso de uso. Por ejemplo, al compartir un vínculo de archivo en el mensaje, es posible que quiera agregar "hasAttachment:true" en los metadatos para que la aplicación del destinatario pueda analizarlo y mostrarlo en consecuencia.

SendChatMessageResult es la respuesta devuelta al enviar un mensaje. Contiene un identificador, que es el identificador único del mensaje.

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)

Recepción de mensajes de chat de un subproceso de chat

Puede recuperar mensajes de chat mediante el sondeo del método list_messages a intervalos especificados.

  • Utilice results_per_page para especificar el número máximo de mensajes que se devuelven por página.
  • Utilice start_time para especificar el primer punto en el tiempo a partir del cual obtener los mensajes.

La enumeración de mensajes devuelve como respuesta un iterador de [ChatMessage].

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 devuelve la versión más reciente del mensaje, incluidas las modificaciones o eliminaciones que se hayan producido en este mediante update_message y delete_message. En el caso de los mensajes eliminados, ChatMessage.deleted_on devuelve un valor datetime que indica cuándo se eliminó el mensaje. En el caso de los mensajes editados, ChatMessage.edited_on devuelve un valor datetime que indica cuándo se editó el mensaje. Puede acceder a la hora original de creación del mensaje mediante ChatMessage.created_on, que se puede usar para ordenar los mensajes.

list_messages devuelve distintos tipos de mensajes que se pueden identificar mediante ChatMessage.type.

Para más información, consulte Tipos de mensajes.

Envío de confirmación de lectura

Puede usar el método send_read_receipt para publicar un evento de confirmación de lectura en una conversación de chat en nombre de un usuario.

  • Use message_id para especificar el identificador del último mensaje leído por el usuario actual.
content='hello world'

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

Adición de un usuario como miembro a la conversación del chat

Una vez que se crea una conversación de chat, puede agregar y quitar usuarios de ella. Al agregar usuarios, les concede acceso para enviar mensajes a la conversación de chat y para agregar o quitar otros participantes. Antes de llamar al método add_participants, asegúrese de que ha adquirido un nuevo token de acceso y una identidad para el usuario. El usuario necesita ese token de acceso para inicializar el cliente de chat.

Mediante el método add_participants se pueden agregar uno o varios usuarios a la conversación de chat, siempre que todos los usuarios dispongan de un nuevo token de acceso e identificación.

Se devuelve list(tuple(ChatParticipant, CommunicationError)). Cuando un participante se agrega correctamente, se espera una lista vacía. En caso de que se produzca un error al agregar un participante, la lista se rellena con los participantes con errores junto con el error producido.

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)

Enumeración de los participantes en una conversación de un chat

En una conversación, los participantes se pueden enumerar de forma similar a como se agregan.

Use list_participants para recuperar los participantes de la conversación. Los comandos siguientes son opcionales:

  • Use results_per_page para especificar el número máximo de participantes que se van a devolver por página.
  • Use skip para omitir los participantes hasta una posición especificada en la respuesta.

La enumeración de participantes devuelve como respuesta un iterador de [ChatParticipant].

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)

Ejecución del código

Ejecute la aplicación desde el directorio de la aplicación con el comando python.

python start-chat.py

Código de ejemplo

Busque el código finalizado de este inicio rápido en GitHub.

Requisitos previos

Instalación

Creación de una aplicación Java

Abra la ventana de terminal o de comandos y navegue hasta el directorio en el que quiere crear la aplicación de Java. Ejecute el siguiente comando para generar el proyecto de Java a partir de la plantilla maven-archetype-quickstart.

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

Observará que el objetivo "generar" creó un directorio con el mismo nombre que el objeto artifactId. En este directorio, el elemento src/main/java directory contiene el código fuente del proyecto, el directorio src/test/java contiene el origen de la prueba y el archivo pom.xml es el modelo de objetos del proyecto o POM.

Actualice el archivo POM de la aplicación para usar Java 8 o posterior:

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

Adición de las referencias de paquete para el SDK de chat

En el archivo POM, haga referencia al paquete azure-communication-chat con las API de 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 la autenticación, el cliente debe hacer referencia al paquete 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 objetos

Las siguientes clases e interfaces controlan algunas de las características principales de Chat SDK de Azure Communication Services para Java.

Nombre Descripción
ChatClient Esta clase es necesaria para la funcionalidad de chat. Cree una instancia de esta con la información de suscripción y úsela para crear, obtener y eliminar subprocesos.
ChatAsyncClient Esta clase es necesaria para la funcionalidad de chat asincrónica. Cree una instancia de esta con la información de suscripción y úsela para crear, obtener y eliminar subprocesos.
ChatThreadClient Esta clase es necesaria para la funcionalidad de subproceso de chat. Obtiene una instancia de a través de la clase ChatClient y la usa para enviar, recibir, actualizar o eliminar mensajes, agregar, quitar u obtener usuarios, enviar notificaciones de escritura y confirmaciones de lectura.
ChatThreadAsyncClient Esta clase es necesaria para la funcionalidad de subproceso de chat asincrónica. Obtiene una instancia de a través de la clase ChatAsyncClient y la usa para enviar, recibir, actualizar o eliminar mensajes, agregar, quitar u obtener usuarios, enviar notificaciones de escritura y confirmaciones de lectura.

Creación de un cliente de chat

Para crear un cliente de chat, usará el punto de conexión de Communication Services y el token de acceso que se generó como parte de los pasos de requisitos previos. Los tokens de acceso de usuario permiten compilar aplicaciones cliente que se autentiquen directamente en Azure Communication Services. Después de generar estos tokens en el servidor, vuelva a pasarlos a un dispositivo cliente. Debe usar la clase CommunicationTokenCredential del SDK común para pasar el token al cliente de chat.

Más información sobre la arquitectura del chat.

Al agregar las instrucciones de importación, asegúrese de agregar solo las importaciones de los espacios de nombres com.azure.communication.chat y com.azure.communication.chat.models, y no del espacio de nombres com.azure.communication.chat.implementation. En el archivo App.java que se generó a través de Maven, puede usar el código siguiente para empezar con:

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

Inicio de un subproceso de chat

Use el método createChatThread para crear un subproceso de chat. createChatThreadOptions se usa para describir la solicitud de subproceso.

  • Use el parámetro topic del constructor para proporcionar un tema a este chat. El tema puede actualizarse después de crear la conversación de chat mediante la función UpdateThread.
  • Use participants para enumerar los participantes de la conversación que se van a agregar a la misma. ChatParticipant toma el usuario que ha creado en el inicio rápido de Token de acceso de usuario.

CreateChatThreadResult es la respuesta devuelta por la creación de una conversación de chat. Contiene un método getChatThread() que devuelve el objeto ChatThread que se puede utilizar para obtener el cliente de la conversación de la que se puede obtener ChatThreadClient para realizar operaciones en la conversación creada: agregar participantes, enviar mensajes, etc. El objeto ChatThread también contiene el método getId() que recupera el identificador único de la conversación.

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

Lista de las conversaciones de chat

Utilice el método listChatThreads para recuperar una lista de las conversaciones de chat existentes.

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

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

Obtención de un cliente de subproceso de chat

El método getChatThreadClient devuelve un cliente de subproceso para un subproceso que ya existe. Se puede usar para realizar operaciones en la conversación creada: agregar participantes, enviar un mensaje, etc. chatThreadId es el identificador único de la conversación del chat existente.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Envío de un mensaje a un subproceso de chat

Utilice el método sendMessage para enviar un mensaje al subproceso creado, identificado mediante chatThreadId. sendChatMessageOptions se utiliza para describir la solicitud del mensaje de chat.

  • Utilice content para proporcionar el contenido del mensaje de chat.
  • Utilice type usa para especificar el tipo de contenido del mensaje de chat, texto o HTML.
  • Utilice senderDisplayName para especificar el nombre para mostrar del remitente.
  • Opcionalmente, use metadata para incluir los datos adicionales que quiera enviar con el mensaje. Este campo proporciona un mecanismo para que los desarrolladores amplíen la funcionalidad de los mensajes de chat y agreguen información personalizada para su caso de uso. Por ejemplo, al compartir un vínculo de archivo en el mensaje, es posible que quiera agregar hasAttachment:true en los metadatos para que la aplicación del destinatario pueda analizarlo y mostrarlo en consecuencia.

La respuesta sendChatMessageResult contiene un id, que es el identificador único del mensaje.

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

Recepción de mensajes de chat de un subproceso de chat

También puede recuperar mensajes de chat mediante el sondeo del método listMessages en el cliente de subproceso de chat a intervalos especificados.

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

listMessages devuelve la versión más reciente del mensaje, incluidas las modificaciones o eliminaciones que se han producido en este mediante .editMessage() y .deleteMessage(). En el caso de los mensajes eliminados, chatMessage.getDeletedOn() devuelve un valor de fecha y hora que indica cuándo se eliminó el mensaje. En el caso de los mensajes editados, chatMessage.getEditedOn() devuelve un valor de fecha y hora que indica cuándo se editó el mensaje. Es posible acceder a la hora original de creación del mensaje mediante chatMessage.getCreatedOn() y se puede usar para ordenar los mensajes.

Obtenga más información sobre los tipos de mensaje aquí: Tipos de mensajes.

Envío de confirmación de lectura

Puede usar el método sendReadReceipt para publicar un evento de confirmación de lectura en un subproceso de chat en nombre de un usuario. chatMessageId es el identificador único del mensaje de chat que se leyó.

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

Mostrar participantes del chat

Use listParticipants para recuperar una colección paginada que contenga los participantes del subproceso 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());
});

Adición de un usuario como participante a la conversación del chat

Una vez que se crea un subproceso de chat, puede agregar y quitar usuarios de este. Al agregar usuarios, les concede acceso para enviar mensajes a la conversación del chat, y agregar o quitar otros participantes. Deberá empezar por obtener un token de acceso y una identidad nuevos para ese usuario. Antes de llamar al método addParticipants, asegúrese de que ha adquirido un token de acceso y una identidad nuevos para ese usuario. El usuario necesitará ese token de acceso para poder inicializar su cliente de chat.

Utilice el método addParticipants para agregar participantes a la conversación.

  • communicationIdentifier es obligatorio y es el elemento CommunicationIdentifier que creó mediante CommunicationIdentityClient en el inicio rápido Token de acceso de usuario.
  • displayName es opcional y es el nombre para mostrar del participante de la conversación.
  • shareHistoryTime es opcional y es la hora a partir de la cual el historial de chat se compartió con el participante. Para compartir el historial desde el inicio del subproceso de chat, establezca esta propiedad en cualquier fecha igual o anterior a la hora de creación del subproceso. Para no compartir ningún historial anterior a la hora en que se agregó el participante, establézcala en la fecha actual. Para compartir el historial parcialmente, establezca la opción en la fecha necesaria.
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);

Ejecución del código

Navegue hasta el directorio que contiene el archivo pom.xml y compile el proyecto mediante el siguiente comando mvn.

mvn compile

A continuación, compile el paquete.

mvn package

Ejecute el siguiente comando mvn para ejecutar la aplicación.

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

Código de ejemplo

Busque el código finalizado de este inicio rápido en GitHub.

Requisitos previos

Antes de comenzar, compruebe lo siguiente:

  • Cree de una cuenta de Azure con una suscripción activa. Para más información, consulte Creación de una cuenta gratuita.

  • Instale Android Studio. Lo usaremos para crear una aplicación de Android a fin de que el inicio rápido instale las dependencias.

  • Cree un recurso de Azure Communication Services. Para más información, consulte Creación de un recurso de Azure Communication Services. Deberá registrar la cadena de conexión y del punto de conexión del recurso para esta guía de inicio rápido.

  • Cree dos usuarios de Communication Services y emítales un token de acceso de usuario. Asegúrese de establecer el ámbito en el chat y anote la cadena del token, así como la cadena user_Id. En este inicio rápido, se creará una conversación con un participante inicial y, después, se agregará un segundo participante a esta. También puede usar la CLI de Azure y ejecutar el comando siguiente con la cadena de conexión para crear un usuario y un token de acceso.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    Para más información, consulte Uso de la CLI de Azure para crear y administrar tokens de acceso.

Instalación

Creación de una nueva aplicación de Android

  1. Abra Android Studio y seleccione Create a new project.
  2. En la ventana siguiente, seleccione Empty Activity como plantilla del proyecto.
  3. Al elegir las opciones, escriba ChatQuickstart como nombre de proyecto.
  4. Haga clic en Siguiente y elija el directorio en el que desea que se cree el proyecto.

Instalación de las bibliotecas

Usaremos Gradle para instalar las dependencias de Communication Services necesarias. Desde la línea de comandos, vaya al directorio raíz del proyecto ChatQuickstart. Abra el archivo build.gradle de la aplicación y agregue las siguientes dependencias en el 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'

Consulte https://search.maven.org/artifact/com.azure.android/azure-communication-common y https://search.maven.org/artifact/com.azure.android/azure-communication-chat para obtener los números de versión más recientes.

Exclusión de metarchivos en las opciones de empaquetado del archivo build.gradle raíz

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

(Opción alternativa) Para instalar bibliotecas a través de Maven

Para importar la biblioteca en su proyecto mediante el sistema de compilación Maven, agréguela a la sección dependencies del archivo pom.xml de la aplicación. Para ello, especifique su identificador de artefacto y la versión que quiere 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>

Configuración de Azure Functions

Consulte Integración de Azure Functions para más información. Se recomienda la integración con Azure Functions para evitar codificar de forma rígida los parámetros de la aplicación.

Configuración de las constantes de la aplicación:

Cree una clase ApplicationConstants que almacene todas las constantes de la aplicación:

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

Configuración de los marcadores de posición

Abra y edite el archivo MainActivity.java. En este inicio rápido, agregaremos el código a MainActivity y veremos la salida en la consola. En este inicio rápido, no se aborda la creación de una interfaz de usuario. En la parte superior del archivo, importe Azure Communication Common y Azure Communication Chat, y otras bibliotecas del sistema:

import com.azure.android.communication.chat.*;
import com.azure.android.communication.chat.models.*;
import com.azure.android.communication.common.*;

import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;

import com.jakewharton.threetenabp.AndroidThreeTen;

import java.util.ArrayList;
import java.util.List;

Copie el código siguiente en la clase MainActivity del archivo 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());
        }
    }

Inicialización de los parámetros de la aplicación

Nota:

Se debe agregar la inicialización de ApplicationConstants a MainActivity.java si se cumple cualquiera de las condiciones siguientes: 1. La característica de notificación de inserción NO está habilitada. 2. La versión de la biblioteca de chat de Azure Communication Services para Android es < "2.0.0". De lo contrario, consulte el paso 11 en Notificaciones de inserción en Android. Consulte la aplicación de ejemplo de la versión del SDK que está consumiendo como referencia.

Se devuelven ACS_ENDPOINT, FIRST_USER_ID y FIRST_USER_ACCESS_TOKEN al llamar a la función de Azure. Consulte Integración de Azure Functions para más información. Usamos la respuesta de la llamada a la función de Azure para inicializar la lista de parámetros:

  • ACS_ENDPOINT: punto de conexión del recurso de Communication Services.
  • FIRST_USER_ID y SECOND_USER_ID: identificadores de usuario válidos de Communication Services generados por el recurso de Communication Services.
  • FIRST_USER_ACCESS_TOKEN: token de acceso de Communication Services para <FIRST_USER_ID>.

Bloque de código para inicializar los parámetros de la aplicación mediante una llamada a la función de 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);
    }

Creación de un cliente de chat

Reemplace el comentario <CREATE A CHAT CLIENT> con el código siguiente (coloque las instrucciones de importación en la parte superior del archivo):

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 objetos

Las siguientes clases e interfaces controlan algunas de las características principales de Chat SDK de Azure Communication Services para JavaScript.

Nombre Descripción
ChatClient/ChatAsyncClient Esta clase es necesaria para la funcionalidad de chat. Cree una instancia de ella con la información de la suscripción y úsela para crear, obtener y eliminar conversaciones, y para suscribirse a eventos de chat.
ChatThreadClient/ChatThreadAsyncClient Esta clase es necesaria para la funcionalidad de subproceso de chat. Obtiene una instancia de a través de la clase ChatClient y la usa para enviar, recibir, actualizar o eliminar mensajes, agregar, quitar u obtener usuarios, enviar notificaciones de escritura y confirmaciones de lectura.

Inicio de un subproceso de chat

Ahora usaremos ChatAsyncClient para crear una conversación con un usuario inicial.

Reemplace el comentario <CREATE A CHAT THREAD> por el código siguiente:

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

Obtención de un cliente de subproceso de chat

Ahora que hemos creado una conversación de chat, obtendremos un elemento ChatThreadAsyncClient para realizar operaciones en la conversación. Reemplace el comentario <CREATE A CHAT THREAD CLIENT> por el código siguiente:

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

Envío de un mensaje a un subproceso de chat

Ahora se enviará un mensaje a ese subproceso.

Reemplace el comentario <SEND A MESSAGE> por el código siguiente:

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

Recepción de mensajes de chat de un subproceso de chat

Notificaciones en tiempo real

Con la señalización en tiempo real, puede suscribirse a nuevos mensajes entrantes y actualizar los mensajes actuales en la memoria en consecuencia. Azure Communication Services admite una lista de eventos a los que se puede suscribir.

Reemplace el comentario <RECEIVE CHAT MESSAGES> con el código siguiente (coloque las instrucciones de importación en la parte superior del archivo):


// 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 conocido: al usar Android Chat y Calling SDK juntos en la misma aplicación, la característica de notificaciones en tiempo real de Chat SDK no funciona. Es posible que se produzca un problema de resolución de dependencias. Mientras se trabaja en una solución, para desactivar la característica de notificaciones en tiempo real, agregue la siguiente información de dependencia en el archivo build.gradle de la aplicación y sondee la API GetMessages para que muestre los mensajes entrantes a los usuarios.

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'

Tenga en cuenta que con la actualización anterior, si la aplicación intenta tocar cualquiera de las API de notificación como chatAsyncClient.startRealtimeNotifications() o chatAsyncClient.addEventHandler(), se producirá un error en tiempo de ejecución.

Notificaciones de inserción

Consulte las notificaciones push de Android para obtener más información.

Adición de un usuario como miembro a la conversación del chat

Reemplace el comentario <ADD A USER> por el código siguiente:

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

Enumeración de usuarios en una conversación

Reemplace el comentario <LIST USERS> con el código siguiente (coloque las instrucciones import en la parte superior del archivo):

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

Eliminación de un usuario de un subproceso de chat

Ahora se eliminará el segundo usuario del subproceso.

Reemplace el comentario <REMOVE A USER> por el código siguiente:

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

Envío de una notificación de escritura

Reemplace el comentario <SEND A TYPING NOTIFICATION> por el código siguiente:

chatThreadAsyncClient.sendTypingNotification().get();

Envío de una confirmación de lectura

Se enviará la confirmación de lectura del mensaje enviado anteriormente.

Reemplace el comentario <SEND A READ RECEIPT> por el código siguiente:

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Enumeración de las confirmaciones de lectura

Reemplace el comentario <READ RECEIPTS> por el código siguiente:

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

Ejecución del código

En Android Studio, presione el botón Ejecutar para compilar y ejecutar el proyecto. En la consola, puede ver la salida del código y la salida del registrador de ChatClient.

Código de ejemplo

Busque el código finalizado de este inicio rápido en GitHub.

Requisitos previos

Antes de comenzar, compruebe lo siguiente:

Instalación

Creación de una aplicación de C#

En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use el comando dotnet new para crear una nueva aplicación de consola con el nombre ChatQuickstart. Este comando crea un sencillo proyecto "Hola mundo" de C# con un solo archivo de origen: Program.cs.

dotnet new console -o ChatQuickstart

Cambie el directorio a la carpeta de la aplicación recién creada y use el comando dotnet build para compilar la aplicación.

cd ChatQuickstart
dotnet build

Instalar el paquete

Instalación de Chat SDK de Azure Communication Services para .NET

dotnet add package Azure.Communication.Chat

Modelo de objetos

Las siguientes clases controlan algunas de las características principales de Chat SDK de Azure Communication Services para C#.

Nombre Descripción
ChatClient Esta clase es necesaria para la funcionalidad de chat. Cree una instancia de esta con la información de suscripción y úsela para crear, obtener y eliminar subprocesos.
ChatThreadClient Esta clase es necesaria para la funcionalidad de subproceso de chat. Obtiene una instancia a través de la clase ChatClient y la usa para enviar, recibir, actualizar o eliminar mensajes, agregar, quitar u obtener participantes, enviar notificaciones de escritura y confirmaciones de lectura.

Creación de un cliente de chat

Para crear un cliente de chat, usará el punto de conexión de Communication Services y el token de acceso que se generó como parte de los pasos de requisitos previos. Debe usar la clase CommunicationIdentityClient de Identity SDK para crear un usuario y emitir un token para pasarlo al cliente de chat.

Obtenga más información sobre los tokens de acceso de usuario.

Este inicio rápido no habla de la creación de un nivel de servicio para administrar tokens para la aplicación de chat, aunque se recomienda. Más información sobre la arquitectura del chat.

Copie los siguientes fragmentos de código y péguelos en el archivo de código fuente: 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);
        }
    }
}

Inicio de un subproceso de chat

Use el método createChatThread en chatClient para crear una conversación de chat.

  • Use topic para proporcionar un tema a este chat; el tema puede actualizarse después de crear el subproceso de chat mediante la función UpdateTopic.
  • Utilice la propiedad participants para pasar una lista de objetos ChatParticipant que se van a agregar al subproceso de chat. El objeto ChatParticipant se inicializó con un objeto CommunicationIdentifier. El objeto CommunicationIdentifier puede ser de tipo CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier o PhoneNumberIdentifier. Por ejemplo, para obtener un objeto CommunicationIdentifier, deberá pasar un identificador de acceso creado siguiendo las instrucciones de Creación de un usuario

El objeto de respuesta del método createChatThread contiene los detalles chatThread. Para interactuar con las operaciones de conversaciones de chat, como agregar participantes, enviar un mensaje, eliminar un mensaje, etc., es necesario crear una instancia del cliente chatThreadClient con el método GetChatThreadClient en el 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;

Obtención de un cliente de subproceso de chat

El método GetChatThreadClient devuelve un cliente de subproceso para un subproceso que ya existe. Se puede usar para realizar operaciones en el subproceso creado: agregar miembros, enviar un mensaje, etc. thread_id es el id. único del subproceso de chat existente.

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

Lista de todas las conversaciones de chat

Use GetChatThreads para recuperar todas las conversaciones de chat de las que forma parte el usuario.

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

Envío de un mensaje a un subproceso de chat

Utilice SendMessage para enviar un mensaje a una conversación.

  • Utilice content para proporcionar el contenido del mensaje; es obligatorio.
  • Utilice type para indicar el tipo de contenido del mensaje, como "text" o "html". Si no se especifica, se establecerá "text".
  • Utilice senderDisplayName para especificar el nombre para mostrar del remitente. Si no se especifica, se establecerá una cadena vacía.
  • Opcionalmente, use metadata para incluir los datos adicionales que quiera enviar con el mensaje. Este campo proporciona un mecanismo para que los desarrolladores amplíen la funcionalidad de los mensajes de chat y agreguen información personalizada para su caso de uso. Por ejemplo, al compartir un vínculo de archivo en el mensaje, es posible que quiera agregar "hasAttachment:true" en los metadatos para que la aplicación del destinatario pueda analizarlo y mostrarlo en consecuencia.
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;

Recepción de mensajes de chat de un subproceso de chat

También puede recuperar mensajes de chat mediante el sondeo del método GetMessages en el cliente de subproceso de chat a intervalos especificados.

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

GetMessages toma un parámetro DateTimeOffset opcional. Si se especifica ese desplazamiento, recibirá los mensajes recibidos, actualizados o eliminados posteriormente. Tenga en cuenta que los mensajes recibidos antes de la hora de desplazamiento, pero editados o eliminados posteriormente, también se devolverán.

GetMessages devuelve la versión más reciente del mensaje, incluidas las modificaciones o eliminaciones que se han producido en este mediante UpdateMessage y DeleteMessage. En el caso de los mensajes eliminados, chatMessage.DeletedOn devuelve un valor de fecha y hora que indica cuándo se eliminó el mensaje. En el caso de los mensajes editados, chatMessage.EditedOn devuelve un valor de fecha y hora que indica cuándo se editó el mensaje. Es posible acceder a la hora original de creación del mensaje mediante chatMessage.CreatedOn y se puede usar para ordenar los mensajes.

GetMessages devuelve distintos tipos de mensajes que se pueden identificar mediante chatMessage.Type. Estos tipos son:

  • Text: mensaje de chat normal enviado por un miembro del subproceso.

  • Html: un mensaje de texto con formato. Tenga en cuenta que los usuarios de Communication Services actualmente no pueden enviar mensajes de texto enriquecido. Este tipo de mensaje es compatible con los mensajes enviados desde usuarios a de Teams a usuarios de Communication Services en escenarios de interoperabilidad de Teams.

  • TopicUpdated: mensaje del sistema que indica que el tema se ha actualizado. (solo lectura).

  • ParticipantAdded: mensaje del sistema que indica que se han agregado uno o varios participantes a la conversación del chat. (solo lectura).

  • ParticipantRemoved: mensaje del sistema que indica que se ha eliminado un miembro de la conversación del chat.

Para obtener más información, consulte Tipos de mensajes.

Adición de un usuario como miembro a la conversación del chat

Una vez que se crea un subproceso, puede agregar y quitar usuarios de este. Al agregar usuarios, les concede acceso para poder enviar mensajes a la conversación, y agregar o quitar otros participantes. Antes de llamar a AddParticipants, asegúrese de que ha adquirido un token de acceso y una identidad nuevos para ese usuario. El usuario necesitará ese token de acceso para poder inicializar su cliente de chat.

Use AddParticipants para agregar uno o varios participantes a la conversación de chat. A continuación se indican los atributos admitidos para cada participante de la conversación:

  • communicationUser es obligatorio y es la identidad del participante de la conversación.
  • displayName es opcional y es el nombre para mostrar del participante de la conversación.
  • shareHistoryTime es opcional y es la hora a partir de la cual el historial de chat se compartió con el 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);

Obtención de los participantes de la conversación

Use GetParticipants para recuperar los participantes de la conversación de chat.

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

Envío de confirmación de lectura

Use SendReadReceipt para notificar a otros participantes que el usuario ha leído el mensaje.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Ejecución del código

Ejecute la aplicación desde el directorio de la aplicación con el comando dotnet run.

dotnet run

Código de ejemplo

Busque el código finalizado de este inicio rápido en GitHub.

Requisitos previos

Antes de comenzar, compruebe lo siguiente:

  • Cree de una cuenta de Azure con una suscripción activa. Para más información, consulte Creación de una cuenta gratuita.

  • Instale Xcode y CocoaPods. Va a usar Xcode para crear una aplicación iOS para el inicio rápido y Cocoapods para instalar las dependencias.

  • Cree un recurso de Azure Communication Services. Para más información, consulte Inicio rápido: Creación y administración de recursos de Communication Services. Deberá registrar la cadena de conexión y del punto de conexión del recurso para esta guía de inicio rápido.

  • Cree dos usuarios de Azure Communication Services y emítales un token de acceso de usuario. Asegúrese de establecer el ámbito en chat y anote la cadena del token, así como la cadena user_Id. En esta guía de inicio rápido, se creará una conversación con un participante inicial y, después, se agregará un segundo participante a esta. También puede usar la CLI de Azure y ejecutar el comando siguiente con la cadena de conexión para crear un usuario y un token de acceso.

    az communication identity token issue --scope chat --connection-string "yourConnectionString"

    Para más información, consulte Uso de la CLI de Azure para crear y administrar tokens de acceso.

Instalación

Creación de una aplicación iOS

Abra Xcode y seleccione Create a new Xcode project (Crear un nuevo proyecto en Xcode). A continuación, seleccione iOS para la plataforma y App (Aplicación) para la plantilla.

Para el nombre del proyecto, escriba ChatQuickstart. A continuación, seleccione Storyboard como interfaz, UIKit App Delegate como ciclo de vida y Swift como lenguaje.

Seleccione Next (Siguiente) y elija el directorio en el que desea que se cree el proyecto.

Instalación de las bibliotecas

Utilice Cocoapods para instalar las dependencias de Communication Services necesarias.

Desde la línea de comandos, vaya al directorio raíz del proyecto de iOS ChatQuickstart. Cree un archivo Podfile con el siguiente comando: pod init.

Abra el archivo Podfile y agregue las siguientes dependencias al destino ChatQuickstart:

pod 'AzureCommunicationChat', '~> 1.3.6'

Instale las dependencias con el comando siguiente: pod install. Tenga en cuenta que esto también crea un área de trabajo de Xcode.

Después de ejecutar pod install, vuelva a abrir el proyecto en Xcode; para ello, seleccione el área .xcworkspace recién creada.

Configuración de los marcadores de posición

Abra el área de trabajo ChatQuickstart.xcworkspace en Xcode y, a continuación, abra ViewController.swift.

En este inicio rápido, va a agregar el código a viewController y verá la salida en la consola de Xcode. En este inicio rápido no se aborda la creación de una interfaz de usuario en iOS.

Al principio de viewController.swift, importe las bibliotecas AzureCommunication y AzureCommunicationChat:

import AzureCommunicationCommon
import AzureCommunicationChat

Copie el código siguiente en el 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)")
            }
        }
    }

Con fines de demostración, usaremos un semáforo para sincronizar el código. En los pasos siguientes, va a reemplazar los marcadores de posición por código de ejemplo mediante la biblioteca de chat de Azure Communication Services.

Creación de un cliente de chat

Para crear un cliente de chat, usará el punto de conexión de Communication Services y el token de acceso que se generó como parte de los pasos de requisitos previos.

Obtenga más información sobre los tokens de acceso de usuario.

Este inicio rápido no habla de la creación de un nivel de servicio para administrar tokens para la aplicación de chat, aunque se recomienda. Más información sobre la arquitectura del chat.

Reemplace el comentario <CREATE A CHAT CLIENT> por el fragmento de código siguiente:

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
)

Reemplace <ACS_RESOURCE_ENDPOINT> por el punto de conexión del recurso de Azure Communication Services. Reemplace <ACCESS_TOKEN> por un token de acceso de Communication Services válido.

Modelo de objetos

Las siguientes clases e interfaces controlan algunas de las características principales de Chat SDK de Azure Communication Services para iOS.

Nombre Descripción
ChatClient Esta clase es necesaria para la funcionalidad de chat. Cree una instancia de ella con la información de la suscripción y úsela para crear, obtener y eliminar conversaciones, y para suscribirse a eventos de chat.
ChatThreadClient Esta clase es necesaria para la funcionalidad de conversación de chat. Obtenga una instancia mediante ChatClient y úsela para enviar, recibir, actualizar y eliminar mensajes. También puede usarla para agregar, quitar y obtener usuarios, y enviar notificaciones de escritura y confirmaciones de lectura.

Inicio de un subproceso de chat

CreateChatThreadResult es la respuesta devuelta por la creación de una conversación de chat. Contiene una propiedad chatThread que es el objeto ChatThreadProperties. Este objeto contiene el valor threadId que se puede usar para obtener un ChatThreadClient para realizar operaciones en el subproceso creado: agregar participantes, enviar mensajes, etc.

Reemplace el comentario <CREATE A CHAT THREAD> por el fragmento de código siguiente:

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

Reemplace <USER_ID> por un identificador de usuario de Communication Services válido.

Aquí va a usar un semáforo para esperar al controlador de finalización antes de continuar. En pasos posteriores, usará el elemento threadId de la respuesta que se devuelve al controlador de finalización.

Lista de todas las conversaciones de chat

Después de crear una conversación de chat, podemos enumerar todas las conversaciones de chat mediante una llamada al método listChatThreads en ChatClient. Reemplace el comentario <LIST ALL CHAT THREADS> por el código siguiente:

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

Obtención de un cliente de subproceso de chat

El método createClient devuelve un ChatThreadClient para un subproceso que ya existe. Se puede usar para realizar operaciones en el subproceso creado: agregar participantes, enviar un mensaje, etc. threadId es el identificador único de la conversación del chat existente.

Reemplace el comentario <GET A CHAT THREAD CLIENT> por el código siguiente:

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

Envío de un mensaje a un subproceso de chat

Utilice el método send para enviar un mensaje a un subproceso identificado mediante threadId.

SendChatMessageRequest se utiliza para describir la solicitud del mensaje:

  • Utilice content para proporcionar el contenido del mensaje de chat.
  • Utilice senderDisplayName para especificar el nombre para mostrar del remitente.
  • Use type para especificar el tipo de mensaje, como "texto" o "html".
  • Opcionalmente, use metadata para incluir los datos adicionales que quiera enviar con el mensaje. Este campo proporciona un mecanismo para que los desarrolladores amplíen la funcionalidad de los mensajes de chat y agreguen información personalizada para su caso de uso. Por ejemplo, al compartir un vínculo de archivo en el mensaje, es posible que quiera agregar "hasAttachment:true" en los metadatos para que la aplicación del destinatario pueda analizarlo y mostrarlo en consecuencia.

SendChatMessageResult es la respuesta que se devuelve al enviar un mensaje. Contiene un identificador que es el identificador único del mensaje.

Reemplace el comentario <SEND A MESSAGE> por el fragmento de código siguiente:

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

Envío de una confirmación de lectura

Puede usar el método sendReadReceipt para publicar un evento de confirmación de lectura en un subproceso de chat en nombre de un usuario. messageId es el identificador único del mensaje de chat que se leyó.

Reemplace el comentario <SEND A READ RECEIPT> por el código siguiente:

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

Recepción de mensajes de chat de un subproceso de chat

Con la señalización en tiempo real, puede suscribirse para escuchar nuevos mensajes entrantes y actualizar los mensajes actuales en la memoria en consecuencia. Azure Communication Services admite una lista de eventos a los que se puede suscribir.

Reemplace el comentario <RECEIVE MESSAGES> por el código siguiente. Después de habilitar las notificaciones, pruebe a enviar nuevos mensajes para ver 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
    }
})

También puede recuperar mensajes de chat mediante el sondeo del método listMessages a intervalos especificados. Ejecute el siguiente fragmento de código de 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()

Adición de un usuario como miembro a la conversación del chat

Una vez que se crea un subproceso, puede agregar y quitar usuarios de este. Al agregar usuarios, les concede acceso para poder enviar mensajes a la conversación, y agregar o quitar otros participantes. Antes de llamar a add, asegúrese de que ha adquirido un token de acceso y una identidad nuevos para ese usuario. El usuario necesitará ese token de acceso para poder inicializar su cliente de chat.

Use el método add de ChatThreadClient para agregar uno o varios participantes a la conversación de chat. A continuación se indican los atributos admitidos para cada participante de la conversación:

  • id es obligatorio y es la identidad del participante de la conversación.
  • displayName es opcional y es el nombre para mostrar del participante de la conversación.
  • shareHistoryTime es opcional y es la hora a partir de la cual el historial de chat se compartió con el participante.

Reemplace el comentario <ADD A USER> por el código siguiente:

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

Reemplace <USER_ID> por el identificador de usuario de Communication Services del usuario que se va a agregar.

Enumeración de usuarios en una conversación

Use el método listParticipants para obtener todos los participantes de una conversación de chat determinada.

Reemplace el comentario <LIST USERS> por el código siguiente:

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

Notificaciones de inserción

Las notificaciones de inserción notifican a los clientes los mensajes entrantes de un subproceso de chat en situaciones en las que la aplicación móvil no se ejecuta en primer plano. Actualmente, el envío de notificaciones de inserción de chat con el Centro de notificaciones se admite para el SDK de IOS en la versión 1.3.0. Consulte el artículo Habilitación de notificaciones de inserción en la aplicación de chat para más información.

Ejecución del código

En Xcode, presione el botón Run (Ejecutar) para compilar y ejecutar el proyecto. En la consola, puede ver la salida del código y la salida del registrador de ChatClient.

Nota: Establezca Build Settings > Build Options > Enable Bitcode en No. Actualmente, el SDK de AzureCommunicationChat para iOS no admite la habilitación de bitcode, lo cual está en seguimiento en el problema de GitHub siguiente.

Código de ejemplo

Busque el código finalizado de este inicio rápido en GitHub.

Requisitos previos

Crear usuario

Complete estos pasos en Power Automate con el flujo de Power Automate abierto en modo de edición.

Para agregar un nuevo paso en el flujo de trabajo mediante el conector de identidad de Communication Services:

  1. En el diseñador, en el paso en el que desee agregar la nueva acción, seleccione Nuevo paso. Como alternativa, para agregar la nueva acción entre pasos, mueva el puntero sobre la flecha entre esos pasos, seleccione el signo más (+) y seleccione Agregar una acción.

  2. En la casilla de búsqueda Seleccionar una operación, introduzca Identidad de Communication Services. En la lista de la lista de acciones, seleccione Crear un usuario.

    Captura de pantalla que muestra la acción Crear usuario del conector de identidad de Azure Communication Services.

  3. Escribir la cadena de conexión. Para obtener la dirección URL de la cadena de conexión en Azure Portal, vaya al recurso Azure Communication Services. En el menú de recursos, seleccione Claves y, a continuación, seleccione Cadena de conexión. Seleccione el icono Copiar para copiar la cadena de conexión.

    Captura de pantalla que muestra la página Claves en el recurso de Azure Communication Services.

  4. Escriba un nombre para la conexión.

  5. Seleccione Mostrar opciones avanzadas y, a continuación, seleccione el ámbito del token. Esta acción generará un token de acceso y su tiempo de expiración con el ámbito especificado. Esta acción también generará un identificador de usuario que es una identidad de usuario de Communication Services.

    Captura de pantalla que muestra la acción Crear usuario del conector de identidad Azure Communication Services.

  6. En Elemento de ámbitos de token, seleccione chat.

    Captura de pantalla que muestra la opción avanzada del conector de chat de Azure Communication Services.

  7. Seleccione Crear. Se muestran el identificador de usuario y un token de acceso.

Crear un hilo de chat

  1. Agregue una nueva acción.

  2. En la casilla de búsqueda Elegir una operación, introduzca Chat de Communication Services. En la lista de acciones, seleccione Crear una conversación de chat.

    Captura de pantalla que muestra la acción Crear hilo de cha del conector de chat de Azure Communication Services.

  3. Escriba la dirección URL del punto de conexión de Communication Services. Para obtener la dirección URL del punto de conexión en Azure Portal, vaya al recurso Azure Communication Services. En el menú de recursos, seleccione Claves y, a continuación, seleccione Punto de conexión.

  4. Escriba un nombre para la conexión.

  5. Seleccione el token de acceso que se generó en la sección anterior y, a continuación, agregue una descripción del tema de conversación de chat. Agregue el usuario creado y escriba un nombre para el participante.

    Captura de pantalla que muestra el diálogo de acción de la conversación Crear chat del conector de chat de Azure Communication Services.

Envío de un mensaje

  1. Agregue una nueva acción.

  2. En la casilla de búsqueda Elegir una operación, introduzca Chat de Communication Services. En la lista de acciones, seleccione Enviar mensaje a la conversación de chat.

    Captura de pantalla que muestra la acción Enviar mensaje de chat del conector de chat de Azure Communication Services.

  3. Escriba el token de acceso, el identificador de subproceso, el contenido y el nombre.

    Captura de pantalla que muestra el diálogo de acción Enviar mensaje de chat del conector de chat de Azure Communication Services.

Enumerar mensajes del hilo del chat

Para comprobar que haya enviado un mensaje correctamente:

  1. Agregue una nueva acción.

  2. En la casilla de búsqueda Elegir una operación, introduzca Chat de Communication Services. En la lista de acciones, seleccione Mostrar mensajes de la conversación de chat.

    Captura de pantalla que muestra la acción de Enumerar mensajes de chat del conector de chat de Azure Communication Services.

  3. Escriba el token de acceso y el identificador de subproceso.

    Captura de pantalla que muestra el diálogo de acción Enumerar mensajes de chat del conector de chat de Azure Communication Services.

Comprobación de la aplicación lógica

Para iniciar manualmente el flujo de trabajo, seleccione Ejecutar en la barra de herramientas del diseñador. El flujo de trabajo crea un usuario, emite un token de acceso para ese usuario y, a continuación, quita el token y elimina al usuario. Para obtener más información, revise Cómo ejecutar el flujo de trabajo.

Ahora, seleccione Enumerar mensajes de conversación de chat. En las salidas de la acción, busque el mensaje que se envió.

Captura de pantalla que muestra los resultados de la acción Enviar mensaje de chat del conector de chat de Azure Communication Services.

Limpieza de recursos de flujo de trabajo

Para limpiar el flujo de trabajo de la aplicación lógica y los recursos relacionados, consulte Limpieza de recursos.

Limpieza de recursos

Si quiere limpiar y quitar una suscripción a Communication Services, puede eliminar el recurso o grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él. Obtenga más información sobre la limpieza de recursos.

Pasos siguientes

En este tutorial, ha aprendido a hacer lo siguiente:

  • Creación de un cliente de chat
  • Creación de un subproceso con dos usuarios
  • Envío de un mensaje al subproceso
  • Recepción de mensajes de un subproceso
  • Eliminación de usuarios de un subproceso

Prueba de la aplicación de elemento principal de chat

Puede que también le interese: