Inicio rápido: Adición de un bot a la aplicación de chat

  • Artículo

Aprenda cómo crear experiencias de IA conversacional en una aplicación de chat mediante el canal de mensajería de chat de Azure Communication Services disponible en Azure Bot Service. En este inicio rápido, creará un bot mediante el SDK de BotFramework. Después, integre el bot en una aplicación de chat que haya creado mediante el SDK de chat de Communication Services.

En esta guía de inicio rápido, ha aprendido a hacer lo siguiente:

Requisitos previos

Creación e implementación de un bot en Azure

Para usar el chat de Azure Communication Services como canal en Azure Bot Service, implemente primero un bot. Para implementar un bot, complete estos pasos:

  • Creación de un recurso de Azure Bot Service
  • Obtención de la contraseña y del identificador de aplicación del bot
  • Creación de una aplicación web que contenga la lógica del bot
  • Creación de un punto de conexión de mensajería para el bot

Creación de un recurso de Azure Bot Service

En primer lugar, use Azure Portal para crear un recurso de Azure Bot Service. El canal de chat de Communication Services admite bots de inquilino único, bots de identidad administrada y bots multiinquilino. Para los fines de este inicio rápido, usaremos un bot multiinquilino.

Para configurar un bot de identidad administrada o de inquilino único, consulte Información de identidad del bot.

En el caso de un bot de identidad administrada, puede que tenga que actualizar la identidad de servicio del bot.

Obtención de la contraseña y del identificador de aplicación del bot

A continuación, obtenga la contraseña y el identificador de aplicación de Microsoft que se asignan al bot cuando se implementa. Estos valores se usan para configuraciones posteriores.

Creación de una aplicación web que contenga la lógica del bot

Para crear una aplicación web para el bot, puede revisar los ejemplos de Bot Builder para su escenario o usar el SDK de Bot Builder para crear una aplicación web. Uno de los ejemplos más sencillos es Bot de eco.

Azure Bot Service normalmente espera a que el controlador de aplicaciones web de la aplicación de bot exponga un punto de conexión con el formato /api/messages. El punto de conexión controla todos los mensajes que se envían al bot.

Para crear la aplicación de bot, use la CLI de Azure para crear un recurso de Azure App Service o cree la aplicación en Azure Portal.

Para crear una aplicación web de bot mediante Azure Portal:

  1. En el portal, seleccione Crear un recurso. En el cuadro de búsqueda, escriba aplicación web. Seleccione el icono Aplicación web.

    Screenshot that shows creating a web app resource in the Azure portal.

  2. En Crear aplicación web, seleccione o escriba los detalles de la aplicación, incluida la región en la que quiere implementarla.

    Screenshot that shows details to set to create a web app deployment.

  3. Seleccione Revisar y crear para validar la implementación y revisar los detalles de esta. Seleccione Crear.

  4. Cuando se cree el recurso de aplicación web, copie la dirección URL del nombre de host que se muestra en los detalles del recurso. La dirección URL formará parte del punto de conexión que cree para la aplicación web.

    Screenshot that shows how to copy the web app endpoint URL.

Creación de un punto de conexión de mensajería para el bot

A continuación, en el recurso de bot, cree un punto de conexión de mensajería de aplicación web:

  1. En Azure Portal, vaya al recurso de Azure Bot. En el menú de recursos, seleccione Configuración.

  2. En Configuración, en Punto de conexión de mensajería, pegue la dirección URL del nombre de host de la aplicación web que copió en la sección anterior. Agregue a la URL con /api/messages.

  3. Seleccione Guardar.

Screenshot that shows how to create a bot messaging endpoint by using the web app hostname.

Implementación de la aplicación web

El último paso para crear un bot es implementar la aplicación web. Para este inicio rápido, use el ejemplo de Echo Bot. La funcionalidad Echo Bot se limita a repetir la entrada del usuario. A continuación, se muestra cómo implementarla en la aplicación web en Azure:

  1. Use Git para clonar este repositorio de GitHub:

    git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

  2. En Visual Studio, abra el proyecto de Echo Bot.

  3. En el proyecto de Visual Studio, abra el archivo Appsettings.json. Pegue el identificador y la contraseña de aplicación de Microsoft que copió anteriormente:

       {
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>"
   }

    A continuación, use Visual Studio para bots de C# a fin de implementar el bot.

    También puede usar una ventana del símbolo del sistema para implementar un bot de Azure.

  4. En el Explorador de soluciones de Visual Studio, haga clic con el botón derecho en el proyecto EchoBot y seleccione Publicar:

    Screenshot that shows publishing your web app from Visual Studio.

  5. Seleccione Nuevo para crear un perfil de publicación. En Destino, seleccione Azure:

    Screenshot that shows how to select Azure as target in a new publishing profile.

    Para el destino específico, seleccione Azure App Service:

    Screenshot that shows how to select Azure App Service as the specific target.

  6. En la configuración de implementación, seleccione la aplicación web en los resultados que aparecen después de iniciar sesión en la cuenta de Azure. Para completar el perfil, seleccione Finalizar y, después, seleccione Publicar para iniciar la implementación.

    Screenshot that shows setting the deployment configuration with the web app name.

Obtener un recurso de Communication Services

Ahora que el bot se ha creado e implementado, cree un recurso de Communication Services que se use para configurar un canal de Communication Services:

  1. Complete los pasos para crear un recurso de Communication Services.

  2. Cree un usuario de Communication Services y emita un token de acceso de usuario. Asegúrese de establecer el ámbito en chat. Copie la cadena de token y la cadena de identificador de usuario.

Habilitar el canal de chat de Communication Services

Cuando tenga un recurso de Communication Services, puede configurar un canal de Communication Services en el recurso del bot. En este proceso, se genera un identificador de usuario para el bot.

  1. En Azure Portal, vaya al recurso de Azure Bot. En el menú de recursos, seleccione Canales. En la lista de canales disponibles, seleccione Azure Communications Services: Chat.

    Screenshot that shows opening the Communication Services Chat channel.

  2. Seleccione Conectar para ver una lista de los recursos de Communication Services que están disponibles en su suscripción.

    Screenshot that shows how to connect a Communication Service resource to the bot.

  3. En el panel Nueva conexión, seleccione el recurso de chat de Communication Services y, después, seleccione Aplicar.

    Screenshot that shows how to save the selected Communication Service resource to create a new Communication Services user ID.

  4. Cuando se comprueben los detalles del recurso, se muestra un identificador de bot en la columna Id. de Azure Communication Services del bot. Puede usar el identificador del bot para representar al bot en una conversación de chat mediante la API AddParticipant del chat de Communication Services. Después de agregar el bot a un chat como participante, este comienza a recibir actividades relacionadas con el chat y puede responder en la conversación del chat.

    Screenshot that shows the new Communication Services user ID assigned to the bot.

Crear una aplicación de chat y agregar el bot como participante

Ahora que tiene el identificador de Communication Services del bot, podrá crear una conversación de chat con el bot como participante.

Creación de una aplicación de C#

  1. Ejecute el comando siguiente para crear una aplicación de C#:

    dotnet new console -o ChatQuickstart

  2. Cambie el directorio a la carpeta de la aplicación nueva y use el comando dotnet build para compilar la aplicación:

    cd ChatQuickstart
dotnet build

Instalar el paquete

Instale el SDK de chat de Communication Services para .NET:

dotnet add package Azure.Communication.Chat

Creación de un cliente de chat

Para crear un cliente de chat, use el punto de conexión de Communication Services y el token de acceso que generó anteriormente. Use la clase CommunicationIdentityClient del SDK de Identity para crear un usuario y emitir un token para pasarlo al cliente de chat. Los tokens de acceso se pueden generar en el portal mediante las instrucciones siguientes.

Copie el código siguiente y péguelo 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 Communication Services endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

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

Inicio de un subproceso de chat con el bot

Use el método createChatThread en chatClient para crear una conversación de chat. Reemplace el identificador por el id. de Communication Services del bot.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", 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:

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

Envío de un mensaje a un subproceso de chat

Para usar SendMessage para enviar un mensaje a un subproceso:

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

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

Puede obtener mensajes de chat mediante el sondeo del método GetMessages en el cliente de conversaciones de chat a intervalos especificados:

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

Compruebe la lista de mensajes de la respuesta de eco del bot a "Hola mundo".

Puede usar JavaScript o los SDK móviles de Azure para suscribirse a las notificaciones de mensajes entrantes:

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

Limpieza de la conversación de chat

Cuando haya terminado de usar la conversación de chat, elimínela:

chatClient.DeleteChatThread(threadId);

Implementación de la aplicación de chat de C#

Para implementar la aplicación de chat:

  1. Abra el proyecto de chat en Visual Studio.

  2. Haga clic con el botón derecho en el proyecto ChatQuickstart y seleccione Publicar:

    Screenshot that shows deploying the chat application to Azure from Visual Studio.

  3. Una vez publicada la solución, ejecútela y compruebe si Echobot devuelve el mensaje de usuario en el símbolo del sistema. Ahora que tiene la solución, puede continuar jugando con las diversas actividades necesarias para los escenarios empresariales que necesita resolver.

Más cosas que puede hacer con un bot

Un bot puede recibir más de un mensaje de texto sin formato de un usuario en un canal de chat de Communications Services. Entre algunas de las actividades que un bot puede recibir de un usuario se incluyen:

  • Actualización de la conversación
  • Actualización de mensajes
  • Eliminación de mensajes
  • Indicador de escritura
  • Actividad de evento
  • Varios datos adjuntos, incluidas las tarjetas adaptativas
  • Datos del canal del bot

En las secciones siguientes, se muestran algunos ejemplos para ilustrar estas características.

Envío de un mensaje de bienvenida cuando se agrega un nuevo usuario al subproceso

La lógica del bot de eco actual acepta la entrada del usuario y la repite. Si quiere agregar lógica adicional, como responder a un evento de Communication Services de incorporación de un participante, copie el código siguiente y péguelo en el archivo de código fuente: EchoBot.cs:

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

Envío de una tarjeta adaptable

Nota:

Las tarjetas adaptables solo se admiten en los casos de uso de Azure Communication Services en los que todos los participantes del chat son usuarios de Azure Communication Services y no para los casos de uso de interoperabilidad de Teams.

Puede enviar una tarjeta adaptativa a la conversación de chat para incrementar la involucración y la eficacia. Una tarjeta adaptativa también le ayuda a comunicarse con los usuarios de varias formas. Puede enviar una tarjeta adaptativa desde un bot si agrega la tarjeta como datos adjuntos de actividad del bot.

Este es un ejemplo de cómo enviar una tarjeta adaptativa:

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);

Obtenga cargas de ejemplo para tarjetas adaptativas en Ejemplos y plantillas.

Para un usuario de chat, el canal de chat de Communication Services agrega un campo a los metadatos del mensaje que indica que el mensaje tiene datos adjuntos. En los metadatos, la propiedad microsoft.azure.communication.chat.bot.contenttype se establece en azurebotservice.adaptivecard.

Este es un ejemplo de un mensaje de chat que tiene asociada una tarjeta adaptativa:

{
    "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
    "senderDisplayName": "BotDisplayName",
    "metadata": {
    "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
    },
 "messageType": "Text"
}

Envío de un mensaje del usuario al bot

Puede enviar un mensaje de texto básico de un usuario al bot de la misma manera que envía un mensaje de texto a otro usuario.

Sin embargo, al enviar un mensaje que tenga datos adjuntos de un usuario a un bot, agregue esta marca a los metadatos del chat de Communication Services:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

Para enviar una actividad de eventos de un usuario a un bot, agregue esta marca a los metadatos del chat de Communication Services:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

En las secciones siguientes se muestran formatos de ejemplo para los mensajes de chat de un usuario a un bot.

Mensaje de texto simple

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

Mensaje con datos adjuntos

{
    "content": "{
                        \"text\":\"sample text\", 
                        \"attachments\": [{
                            \"contentType\":\"application/vnd.microsoft.card.adaptive\",
                            \"content\": { \"*adaptive card payload*\" }
                        }]
        }",
    "senderDisplayName": "Acs-Dev-Bot",
    "metadata": {
        "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
        "text": "random text",
        "key1": "value1",
        "key2": "{\r\n  \"subkey1\": \"subValue1\"\r\n}"
    },
        "messageType": "Text"
}

Mensaje con una actividad de evento

Una carga del evento incluye todos los campos JSON en el contenido del mensaje, excepto Name. El campo Name contiene el nombre del evento.

En el ejemplo siguiente, el nombre del evento endOfConversation con la carga "{field1":"value1", "field2": { "nestedField":"nestedValue" }} se envía al bot:

{
    "content":"{
                   \"name\":\"endOfConversation\",
                   \"field1\":\"value1\",
                   \"field2\": {  
                       \"nestedField\":\"nestedValue\"
                    }
               }",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{  
                   "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
                   "text":"random text",
                   "key1":"value1",
                   "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n}"
               },
    "messageType": "Text"
}

El campo de metadatos microsoft.azure.communication.chat.bot.contenttype solo es necesario en un mensaje que se envía desde un usuario a un bot.

Campos de actividad de bot admitidos

En las secciones siguientes se describen los campos de actividad de bot admitidos para los flujos de bot a usuario y los flujos de usuario a bot.

Flujo del bot al usuario

Los campos de actividad de bot siguientes son compatibles con los flujos de bot a usuario.

Actividades

  • Message
  • Escritura

Campos de actividad de mensaje

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (convertido a SenderDisplayName de Communication Services).
  • ChannelData (convertido a Chat Metadata de Communication Services. Si los valores de asignación de ChannelData son objetos, se serializarán en formato JSON y se enviarán como cadena).

Flujo del usuario al bot

Estos campos de actividad de bot son compatibles con los flujos de usuario a bot.

Actividades y campos

  • Message

    • Id (id. de mensaje de chat de Communication Services)
    • TimeStamp
    • Text
    • Attachments

  • Actualización de la conversación

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Actualización de mensajes

    • Id (id. de mensaje de chat de Communication Services actualizado)
    • Text
    • Attachments

  • Eliminación de mensajes

    • Id (id. de mensaje de chat de Communication Services eliminado)

  • evento

    • Name
    • Value

  • Escritura

Otros campos comunes

  • Recipient.Id y Recipient.Name (id. de usuario de chat y nombre para mostrar de Communication Services)
  • From.Id y From.Name (id. de usuario de chat y nombre para mostrar de Communication Services)
  • Conversation.Id (id. de conversación de chat de Communication Services)
  • ChannelId (chat de Communication Services, si está vacío)
  • ChannelData (metadatos de mensaje de chat de Communication Services)

Patrones de entrega del bot

A veces, un bot no entiende o no puede responder a una pregunta. Un cliente puede pedir en el chat que se le ponga en contacto con un agente humano. En estos escenarios, la conversación del chat debe pasarse desde el bot a un agente humano. Puede diseñar la aplicación para realizar la transición de la conversación del bot a un humano.

Control de la comunicación de bot a bot

En algunos casos de uso, deben agregarse dos bots a la misma conversación de chat para proporcionar servicios diferentes. En este escenario, puede que tenga que asegurarse de que un bot no envíe respuestas automatizadas a los mensajes del otro bot. Si no se controla correctamente, la interacción automatizada de los bots entre sí puede dar lugar a un bucle infinito de mensajes.

Puede comprobar la identidad de usuario de Communication Services del remitente de un mensaje en la propiedad From.Id de la actividad. Compruebe si pertenece a otro bot. Después, realice la acción necesaria para evitar un flujo de comunicación de bot a bot. Si este tipo de escenario genera grandes volúmenes de llamadas, el canal de chat de Communication Services limita las solicitudes y uno de los bots no podrá enviar ni recibir mensajes.

Obtenga más información sobre los límites.

Solución de problemas

En las secciones siguientes se describen las formas de solucionar escenarios comunes.

No se puede agregar el canal de chat

En el portal para desarrolladores de Microsoft Bot Framework, vaya a Configuración>Mensajería de bot para comprobar que el punto de conexión se ha establecido correctamente.

El bot obtiene una excepción de prohibido mientras responde a un mensaje

Compruebe que la contraseña y el identificador de aplicación de Microsoft del bot se hayan guardado correctamente en el archivo de configuración del bot que se carga en la aplicación web.

El bot no se puede agregar como participante

Compruebe que el id. de Communication Services del bot se usa correctamente al enviar una solicitud para agregar un bot a una conversación de chat.

Pasos siguientes

Pruebe la aplicación de demostración del bot de chat para un chat de uno a uno entre un usuario de chat y un bot a través del componente de UI BotFramework WebChat.