Compartir a través de

Biblioteca cliente de Chat de Comunicación de Azure para .NET: versión 1.1.2

  • Artículo

Este paquete contiene un SDK de C# para Azure Communication Services para chat.

Código | fuentePaquete (NuGet) | Documentación del producto

Introducción

Instalar el paquete

Instale la biblioteca cliente de Chat de comunicación de Azure para .NET con NuGet:

dotnet add package Azure.Communication.Chat

Requisitos previos

Necesita una suscripción de Azure y un recurso de Communication Service para usar este paquete.

Para crear un servicio de comunicación, puede usar Azure Portal, la Azure PowerShell o la biblioteca cliente de administración de .NET.

Autenticar el cliente

Tokens de acceso de usuario

Los tokens de acceso de usuario permiten compilar aplicaciones cliente que se autentiquen directamente en Azure Communication Services. Para la generación de tokens de acceso de usuario, consulte Tokens de acceso de usuario.

Uso de las instrucciones

using Azure.Communication.Identity;
using Azure.Communication.Chat;

Crear un ChatClient

Esto le permitirá crear, obtener o eliminar subprocesos de chat.

ChatClient chatClient = new ChatClient(
    endpoint,
    new CommunicationTokenCredential(userToken));

Crear un chatThreadClient

ChatThreadClient le permitirá realizar operaciones específicas de un subproceso de chat, como actualizar el tema del subproceso de chat, enviar un mensaje, agregar participantes al subproceso de chat, etc.

Puede crear una instancia de un nuevo ChatThreadClient mediante la operación GetChatThread de ChatClient con un identificador de subproceso existente:

ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(chatThread.Id);

Conceptos clave

Una conversación de chat se representa mediante un subproceso. Cada usuario del subproceso se denomina participante del subproceso. Los participantes de subprocesos pueden chatear entre sí de forma privada en un chat de 1:1 o agruparse en un chat de grupo 1:N. Los usuarios también obtienen actualizaciones casi en tiempo real para cuando otros escriben y cuando han leído los mensajes.

Una vez inicializada una ChatClient clase, puede realizar las siguientes operaciones de chat:

Creación de un subproceso

CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new ChatParticipant[] { });
ChatThreadProperties chatThread = createChatThreadResult.ChatThread;

Obtener un subproceso

ChatThread chatThread = chatClient.GetChatThread(chatThread.Id);

Obtener todos los subprocesos para el usuario

Pageable<ChatThreadItem> threads = chatClient.GetChatThreads();

Eliminación de un subproceso

chatClient.DeleteChatThread(chatThread.Id);

Una vez inicializada una ChatThreadClient clase, puede realizar las siguientes operaciones de chat:

Actualizar un subproceso

chatThreadClient.UpdateTopic(topic: "Launch meeting");

Envío de un mensaje

SendChatMessageResult sendChatMessageResult = chatThreadClient.SendMessage("Let's meet at 11am");

Actualización de un mensaje

chatThreadClient.UpdateMessage(sendChatMessageResult.Id, content: "Instead of 11am, let's meet at 2pm");

Obtención de mensajes

ChatMessage message = chatThreadClient.GetMessage(sendChatMessageResult.Id);

Eliminar un mensaje

chatThreadClient.DeleteMessage(sendChatMessageResult.Id);

Obtener mensajes

Pageable<ChatMessage> messages = chatThreadClient.GetMessages();

Obtener una lista de participantes

Pageable<ChatParticipant> chatParticipants = chatThreadClient.GetParticipants();

Agregar participantes

chatThreadClient.AddParticipants(participants: new[] { new ChatParticipant(participantIdentifier) });

Quitar un participante

chatThreadClient.RemoveParticipant(identifier: participantIdentifier);

Envío de una notificación de escritura

chatThreadClient.SendTypingNotification();

Obtener una lista de recibos de lectura

Pageable<ChatMessageReadReceipt> readReceipts = chatThreadClient.GetReadReceipts();

Envío de una confirmación de lectura

chatThreadClient.SendReadReceipt(sendChatMessageResult.Id);

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de clienteAcceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes, entre las que se incluyen:

Operaciones de subprocesos

Creación de un subproceso

Use CreateChatThread para crear un objeto de cliente de subproceso de chat.

  • Use topic para proporcionar un tema de subproceso.
  • Estos son los atributos admitidos para cada participante del subproceso:
    • communicationUser, obligatorio, es la identificación del participante del subproceso.
    • displayName, opcional, es el nombre para mostrar del participante del subproceso.
    • shareHistoryTime es opcional y es la hora a partir de la cual el historial de chat se compartió con el participante.

ChatThreadClient es el resultado devuelto al crear un subproceso, puede usarlo para realizar otras operaciones en el subproceso de chat.

ChatClient chatClient = new ChatClient(
    endpoint,
    new CommunicationTokenCredential(userToken));

var chatParticipant = new ChatParticipant(identifier: kimberly)
{
    DisplayName = "Kim"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
string threadId = createChatThreadResult.ChatThread.Id;
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId);

Obtener un subproceso

Use GetChatThread para recuperar un subproceso de chat del servicio. threadId es el identificador único del subproceso.

ChatThreadProperties chatThread = await chatThreadClient.GetPropertiesAsync();

Obtener subprocesos (para un participante)

Use GetChatThreads para obtener la lista de subprocesos de chat para el participante que creó una instancia de chatClient.

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

Eliminación de un subproceso

Use DeleteChatThread para eliminar un subproceso. threadId es el identificador único del subproceso.

await chatClient.DeleteChatThreadAsync(threadId);

Actualizar un subproceso

Use UpdateTopic para actualizar el tema del subproceso de chat.

  • topic se usa para describir el tema actualizado del subproceso.
await chatThreadClient.UpdateTopicAsync(topic: "new topic !");

Operaciones de mensaje

Envío de un mensaje

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.
SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(content:"hello world");
var messageId = sendChatMessageResult.Id;

Obtención de mensajes

Utilice GetMessage para recuperar un mensaje del servicio. messageId es el identificador único del mensaje.

ChatMessage es la respuesta devuelta al obtener un mensaje, contiene un identificador, que es el identificador único del mensaje, entre otros campos. Consulte Azure.Communication.Chat.ChatMessage.

ChatMessage chatMessage = await chatThreadClient.GetMessageAsync(messageId);

Obtener mensajes

Use GetMessages para recuperar todos los mensajes del subproceso de chat.

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

Actualización de un mensaje

Use UpdateMessage para actualizar un mensaje.

  • messageId es el identificador único del mensaje.
  • content es el contenido del mensaje que se va a actualizar.
await chatThreadClient.UpdateMessageAsync(messageId, "updated message content");

Eliminar un mensaje

Use DeleteMessage para eliminar un mensaje.

  • messageId es el identificador único del mensaje.
await chatThreadClient.DeleteMessageAsync(messageId);

Operaciones de participantes de subprocesos

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

Agregar participantes de subprocesos

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, obligatorio, es la identificación del participante del subproceso.
  • 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 participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants);

Quitar participante de subprocesos

Use RemoveParticipant para quitar un participante de subproceso del subproceso. communicationUser es la identificación del participante del chat.

await chatThreadClient.RemoveParticipantAsync(gloria);

Operaciones de eventos

Envío de notificación de escritura

Use SendTypingNotification para indicar que el usuario está escribiendo una respuesta en la conversación.

await chatThreadClient.SendTypingNotificationAsync();

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

Obtención de confirmaciones de lectura

Use GetReadReceipts para comprobar el estado de los mensajes y ver cuáles han leído otros participantes de una conversación de chat.

AsyncPageable<ChatMessageReadReceipt> allReadReceipts = chatThreadClient.GetReadReceiptsAsync();
await foreach (ChatMessageReadReceipt readReceipt in allReadReceipts)
{
    Console.WriteLine($"{readReceipt.ChatMessageId}:{((CommunicationUserIdentifier)readReceipt.Sender).Id}:{readReceipt.ReadOn}");
}

Solución de problemas

Respuestas de servicio

RequestFailedException Se produce como respuesta de servicio para las solicitudes incorrectas. La excepción contiene información sobre qué código de respuesta se devolvió desde el servicio.

try
{
    CreateChatThreadResult createChatThreadErrorResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { josh });
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.Message);
}

Pasos siguientes

Más información sobre chat en Azure Communication Services

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.