Adición de un bot a la aplicación de chat

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. A continuación, integre el bot en una aplicación de chat que cree mediante el SDK de chat de Communication Services.

En este artículo se describe cómo:

Creación e implementación de un bot en Azure
Obtener un recurso de Communication Services
Habilitar el canal de chat de Communication Services para el bot
Crear una aplicación de chat y agregar el bot como participante
Explorar más características para su bot

Prerequisites

Una cuenta de Azure y una suscripción activa. Cree una cuenta gratuita.
Visual Studio 2019 o posterior.
Tener la última versión de .NET Core. En este inicio rápido, se usa .NET Core 3.1. Asegúrese de instalar la versión correspondiente a la instancia de Visual Studio, de 32 o de 64 bits.
SDK de Bot Framework

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 del identificador y la contraseña de la aplicación del bot
Creación de una aplicación web para contener 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, cree un recurso de Azure Bot Service en Azure Portal. El canal de chat de Communication Services admite bots de identidad administrada y bots de un solo inquilino.

En este ejemplo se muestra cómo usar una identidad administrada con el bot. Si en su lugar usa un bot de inquilino único, consulte la instrucción para configurar la identidad del Bot de inquilino único.

En el caso de los bots de identidad administrada, asegúrese de actualizar también la aplicación con la identidad de Bot Service para garantizar la configuración adecuada.

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

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

Creación de una aplicación web para contener 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 bot Builder SDK para crear una aplicación web. Uno de los ejemplos más sencillos es Echo 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.

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

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

En el portal, seleccione Crear un recurso. En el cuadro de búsqueda, escriba aplicación web. Seleccione el icono Aplicación web.
En Crear aplicación web, seleccione o escriba los detalles de la aplicación, incluida la región en la que quiere implementarla.
Seleccione Revisar y crear para validar la implementación y revisar los detalles de esta. Seleccione Crear.
Cuando se crea 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.

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:

En Azure Portal, vaya al recurso de Azure Bot. En el menú de recursos, seleccione Configuración.
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.
Haga clic en Guardar.

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

Use Git para clonar este repositorio de GitHub:

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

En Visual Studio, abra el proyecto de Echo Bot.

En el proyecto de Visual Studio, abra el archivo Appsettings.json. Rellene lo siguiente con el identificador de aplicación de Microsoft e id. de inquilino:

   {
     "MicrosoftAppType": "UserAssignedMSI"
     "MicrosoftAppId": "<Client ID of the user-assigned managed identity>",
     "MicrosoftAppPassword": "", // Not applicable. Leave this blank for a user-assigned managed identity bot.
     "MicrosoftAppTenantId": "<The tenant ID of the user-assigned managed identity>"
   }

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

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

En el Explorador de soluciones de Visual Studio, haga clic con el botón derecho en el proyecto EchoBot y seleccione Publicar:
Seleccione Nuevo para crear un perfil de publicación. En Destino, seleccione Azure:

Para el destino específico, seleccione Azure App Service:
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.

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:

Complete los pasos para crear un recurso de Communication Services.
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.

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.
Seleccione Conectar para ver una lista de los recursos de Communication Services que están disponibles en su suscripción.
En el panel Nueva conexión, seleccione el recurso de chat de Communication Services y, después, seleccione Aplicar.
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.

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#

Ejecute el siguiente comando para crear una aplicación de C#:
```
dotnet new console -o ChatQuickstart
```
Cambie el directorio a la nueva carpeta de la aplicación y use el comando para compilar la dotnet build aplicación:
```
cd ChatQuickstart
dotnet build
```

Instalación del 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 mensajería, use el punto de conexión de Servicios de Comunicación y el token de acceso de usuario que generó anteriormente. Use la CommunicationIdentityClient clase del SDK de identidad 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 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);
        }
    }
}

Iniciar un hilo de chat con el bot

Utiliza el método createChatThread en chatClient para crear un hilo de chat. Reemplaza el ID por el ID de Servicios de Comunicación 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 conversación de chat

El GetChatThreadClient método 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 hilo:

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

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Recibir mensajes de chat de un hilo de chat

Puede obtener mensajes de chat sondeando el método GetMessages en el cliente del hilo de chat a intervalos establecidos.

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 Hello World.

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

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

Limpieza del hilo de chat

Cuando haya terminado de usar el hilo de chat, elimine el hilo.

chatClient.DeleteChatThread(threadId);

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

Para implementar la aplicación de chat:

En Visual Studio, abra el proyecto de chat.
Haga clic con el botón derecho en el proyecto ChatQuickstart y seleccione Publicar:
Una vez publicada la solución, ejecútela y compruebe si el bot de eco devuelve el mensaje de usuario en el símbolo del sistema. Ahora que tiene la solución, puede continuar jugando con las distintas actividades necesarias para los escenarios empresariales que podría necesitar 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 eventos
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

Note

Las tarjetas adaptables solo se admiten en casos de uso de Azure Communication Services en los que todos los participantes del chat son usuarios de Azure Communication Services y no para 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 microsoft.azure.communication.chat.bot.contenttype de metadatos solo es necesario en un mensaje enviado 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 de bot a usuario

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

Activities

Message
Typing

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 de usuario a 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)
Event
- Name
- Value
Typing

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.

Troubleshoot

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 está configurado 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 1:1 entre un usuario de chat y un bot a través del componente botFramework WebChat UI.

Para obtener más información sobre cómo agregar un bot de OpenAI, consulte Integración de un bot de OpenAI con chat.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-07-29