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

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.

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 de bot y publicación en una aplicación web

Para crear un bot, puede realizar una de las siguientes acciones:

  • Revise Ejemplos de Bot Builder para su escenario, cree una aplicación web y, a continuación, implemente el ejemplo del bot en ella.
  • Use el SDK de Bot Builder para crear y publicar un bot en una aplicación web.

Para este inicio rápido, usaremos el ejemplo Bot de eco en los ejemplos de Bot Builder.

Creación de una aplicación web para contener la aplicación de bot

Para crear la aplicación web, 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.

    Captura de pantalla que muestra la creación de un recurso de aplicación web en 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.

    Captura de pantalla que muestra los detalles para establecer y crear una implementación de aplicación web.

  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.

    Captura de pantalla que muestra cómo copiar la dirección URL del punto de conexión de la aplicación web.

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

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.

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.

Captura de pantalla que muestra cómo crear un punto de conexión de mensajería de bot mediante el nombre de host de la aplicación web.

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 Bot de eco. 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:

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

    A continuación, use Visual Studio o VS Code 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:

    Captura de pantalla que muestra la publicación de la aplicación web desde Visual Studio.

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

    Captura de pantalla que muestra cómo seleccionar Azure como destino en un nuevo perfil de publicación.

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

    Captura de pantalla que muestra cómo seleccionar Azure App Service como destino específico.

  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.

    Captura de pantalla que muestra cómo establecer la configuración de implementación con el nombre de la aplicación web.

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.

    Captura de pantalla que muestra la apertura del canal de chat de Communication Services.

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

    Captura de pantalla que muestra cómo conectar un recurso de Communication Services al bot.

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

    Captura de pantalla que muestra cómo guardar el recurso de Communication Services seleccionado para crear un nuevo identificador de usuario de Communication Services.

  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.

    Captura de pantalla que muestra el nuevo identificador de usuario de Communication Services asignado al 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.

Siga el inicio rápido "Agregar chat a la aplicación"

Siga los pasos descritos en el inicio rápido Agregar chat a la aplicación para crear una aplicación de chat.

  1. Reemplace <Resource_Endpoint> por el punto de conexión de Communication Services del paso Obtener un recurso de Communication Service.
  2. Reemplace <Access_Token> por el token de acceso de usuario del paso Obtener un recurso de Communication Service.
  3. Reemplace <Access_ID> por los bots ACS_ID del paso Habilitar el canal de chat de Communication Services.

Ejecución local de la aplicación de chat de C#

Para ejecutar la aplicación de chat localmente, use el comando dotnet run:

dotnet run

Debería recibir un mensaje del bot en la consola que indica "Hola mundo".

Ejemplo:

1730405535010:Hello World

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.