Partilhar via

Adicionar um bot ao seu aplicativo de bate-papo

Saiba como criar experiências de IA de conversação em um aplicativo de chat usando o canal de mensagens de Chat dos Serviços de Comunicação do Azure que está disponível no Serviço de Bot do Azure. Neste início rápido, você cria um bot usando o SDK do BotFramework. Em seguida, integre o bot em um aplicativo de chat criado usando o SDK de Chat dos Serviços de Comunicação.

Este artigo descreve como:

Prerequisites

Criar e implantar um bot no Azure

Para usar o chat dos Serviços de Comunicação do Azure como um canal no Serviço de Bot do Azure, primeiro implante um bot. Para implantar um bot, conclua estas etapas:

  • Criar um recurso do Serviço de Bot do Azure
  • Obter o ID e a senha do aplicativo do bot
  • Criar um aplicativo Web para manter a lógica do bot
  • Criar um endpoint de mensagens para o bot

Criar um recurso do Serviço de Bot do Azure

Primeiro, crie um recurso do Serviço de Bot do Azure no portal do Azure. O canal de Chat dos Serviços de Comunicação suporta bots de identidade geridos e bots de inquilino único.

Este exemplo demonstra como usar uma identidade gerenciada com seu bot. Se, em vez disso, estiver a usar um bot de inquilino único, consulte as instruções para configurar a identidade do bot de inquilino único.

Para bots de identidade gerenciados, certifique-se também de atualizar seu aplicativo com a identidade do Serviço de Bot para garantir a configuração adequada.

Obter o ID e a senha do aplicativo do bot

Em seguida, obtenha a ID do aplicativo Microsoft e a senha atribuídas ao seu bot quando implantado. Use esses valores para configurações posteriores.

Criar um aplicativo Web para manter a lógica do bot

Para criar um aplicativo Web para seu bot, você pode revisar exemplos do Bot Builder para seu cenário ou usar o SDK do Bot Builder para criar um aplicativo Web. Um dos exemplos mais simples é o Echo Bot.

O Serviço de Bot do Azure normalmente espera que o Bot Application Web App Controller exponha um ponto de extremidade no formato /api/messages. O ponto de extremidade processa todas as mensagens enviadas ao bot.

Para criar o aplicativo bot, use a CLI do Azure para criar um recurso do Serviço de Aplicativo do Azure ou crie o aplicativo no portal do Azure.

Para criar um aplicativo Web de bot usando o portal do Azure:

  1. No portal, selecione Criar um recurso. Na caixa de pesquisa, introduza aplicação Web. Selecione o tile Aplicativo Web.

    Captura de ecrã que mostra a criação de um recurso de aplicação Web no portal do Azure.

  2. Em Criar Aplicativo Web, selecione ou insira detalhes para o aplicativo, incluindo a região onde você deseja implantar o aplicativo.

    Captura de tela que mostra os detalhes a serem definidos para criar uma implantação de aplicativo Web.

  3. Selecione Revisar e Criar para validar a implementação e rever os detalhes da implementação. Em seguida, selecione Criar.

  4. Quando o recurso da aplicação web for criado, copie a URL do nome de anfitrião mostrada nos detalhes do recurso. A URL faz parte do ponto de extremidade que você cria para o aplicativo Web.

    Captura de tela que mostra como copiar a URL do ponto de extremidade do aplicativo Web.

Criar um endpoint de mensagens para o bot

Em seguida, no recurso de bot, crie um ponto de extremidade de mensagens do aplicativo Web:

  1. No portal do Azure, vá para seu recurso de Bot do Azure. No menu de recursos, selecione Configuração.

  2. Em Configuração, para o Ponto de extremidade de mensagens, cole a URL do nome do host da aplicação web copiado na seção anterior. Anexe o URL com /api/messages.

  3. Selecione Guardar.

Captura de ecrã que mostra como criar um endpoint de mensagens para bots usando o nome de host da aplicação web.

Implantar o aplicativo Web

A etapa final para criar um bot é implantar o aplicativo Web. Para este início rápido, use o exemplo do Echo Bot. A funcionalidade do Echo Bot é limitada a ecoar a entrada do usuário. Veja como implantá-lo em seu aplicativo Web no Azure:

  1. Use o Git para clonar este repositório GitHub:

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

  2. No Visual Studio, abra o projeto Echo Bot.

  3. No projeto do Visual Studio, abra o arquivo Appsettings.json . Preencha o seguinte com a ID do aplicativo Microsoft e a ID do locatário:

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

    Em seguida, use o Visual Studio para bots C# para implantar o bot.

    Você também pode usar uma janela do Prompt de Comando para implantar um bot do Azure.

  4. No Visual Studio, no Gerenciador de Soluções, clique com o botão direito do mouse no projeto EchoBot e selecione Publicar:

    Captura de tela que mostra a publicação de seu aplicativo Web do Visual Studio.

  5. Selecione Novo para criar um novo perfil de publicação. Para Destino, selecione Azure:

    Captura de tela que mostra como selecionar o Azure como destino em um novo perfil de publicação.

    Para o destino específico, selecione Serviço de Aplicativo do Azure:

    Captura de tela que mostra como selecionar o Serviço de Aplicativo do Azure como o destino específico.

  6. Na configuração de implantação, selecione o aplicativo Web nos resultados que aparecem depois que você entra na sua conta do Azure. Para concluir o perfil, selecione Concluir e, em seguida, selecione Publicar para iniciar a implantação.

    Captura de tela que mostra a configuração de implantação com o nome do aplicativo Web.

Obter um recurso de Serviços de Comunicação

Agora que seu bot foi criado e implantado, crie um recurso de Serviços de Comunicação para usar para configurar um canal de Serviços de Comunicação:

  1. Conclua as etapas para criar um recurso de Serviços de Comunicação.

  2. Crie um utilizador dos Serviços de Comunicação e emita um token de acesso de utilizador. Certifique-se de definir o escopo para chat. Copie a cadeia de token e a cadeia de ID de utilizador.

Habilitar o canal de Chat dos Serviços de Comunicação

Quando você tem um recurso de Serviços de Comunicação, pode configurar um canal de Serviços de Comunicação no recurso de bot. Nesse processo, um ID de usuário é gerado para o bot.

  1. No portal do Azure, vá para seu recurso de Bot do Azure. No menu de recursos, selecione Canais. Na lista de canais disponíveis, selecione Serviços de Comunicação do Azure - Chat.

    Captura de ecrã que mostra a abertura do canal de Chat dos Serviços de Comunicação.

  2. Selecione Conectar para ver uma lista de recursos dos Serviços de Comunicação disponíveis em sua assinatura.

    Captura de tela que mostra como conectar um recurso do Serviço de Comunicação ao bot.

  3. No painel Nova Conexão, selecione o recurso de chat dos Serviços de Comunicação e selecione Aplicar.

    Captura de ecrã que mostra como guardar o recurso do Serviço de Comunicação selecionado para criar um novo ID de utilizador dos Serviços de Comunicação.

  4. Quando os detalhes do recurso são verificados, uma ID de bot é mostrada na coluna ID dos Serviços de Comunicação do Azure Bot. Pode usar o ID do bot para representar o bot numa conversa de chat utilizando a API AddParticipant do Chat dos Serviços de Comunicação. Depois de adicionar o bot a um bate-papo como participante, o bot começa a receber atividades relacionadas ao bate-papo e pode responder no tópico de bate-papo.

    Captura de tela que mostra o novo ID de usuário dos Serviços de Comunicação atribuído ao bot.

Criar um aplicativo de bate-papo e adicionar o bot como participante

Agora que você tem a ID dos Serviços de Comunicação do bot, pode criar um thread de bate-papo com o bot como participante.

Crie uma nova aplicação C#

  1. Execute o seguinte comando para criar um aplicativo C#:

    dotnet new console -o ChatQuickstart

  2. Altere seu diretório para a nova pasta do aplicativo e use o dotnet build comando para compilar seu aplicativo:

    cd ChatQuickstart
dotnet build

Instale o pacote

Instale o SDK de Chat dos Serviços de Comunicação para .NET:

dotnet add package Azure.Communication.Chat

Criar um cliente de chat

Para criar um cliente de chat, use o ponto de extremidade dos Serviços de Comunicação e o token de acesso de usuário gerado anteriormente. Use a CommunicationIdentityClient classe do SDK de identidade para criar um usuário e emitir um token para passar para seu cliente de chat. Os tokens de acesso podem ser gerados no portal usando as seguintes instruções.

Copie o código a seguir e cole-o no arquivo de origem 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 um tópico de bate-papo com o bot

Utilize o método createChatThread em chatClient para criar uma sequência de chat. Substitua a ID pela ID dos Serviços de Comunicação do 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;

Obter um cliente de thread de chat

O GetChatThreadClient método retorna um cliente de thread para um thread que já existe:

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

Enviar uma mensagem para um tópico de chat

Para usar SendMessage para enviar uma mensagem para um thread:

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

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Receber mensagens de chat a partir de um tópico de chat

Você pode obter mensagens de bate-papo recorrendo ao método GetMessages no cliente do thread de bate-papo em intervalos regulares.

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

Verifique a lista de mensagens para a resposta de eco do bot para Hello World.

Você pode usar JavaScript ou os SDKs móveis do Azure para assinar notificações de mensagens de entrada:

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

Limpar o tópico de bate-papo

Quando terminar de usar o thread de chat, exclua o thread:

chatClient.DeleteChatThread(threadId);

Implantar o aplicativo de chat C#

Para implantar o aplicativo de chat:

  1. No Visual Studio, abra o projeto de chat.

  2. Clique com o botão direito do mouse no projeto ChatQuickstart e selecione Publicar:

    Captura de tela que mostra a implantação do aplicativo de chat no Azure a partir do Visual Studio.

  3. Depois de publicar a solução, execute-a e verifique se o bot Echo ecoa a mensagem do usuário no prompt de comando. Agora que você tem a solução, você pode continuar a jogar com as várias atividades necessárias para os cenários de negócios que você pode precisar resolver.

Mais coisas que você pode fazer com um bot

Um bot pode receber mais do que uma mensagem de texto simples de um usuário em um canal de bate-papo dos Serviços de Comunicação. Algumas das atividades que um bot pode receber de um usuário incluem:

  • Atualização da conversação
  • Atualização da mensagem
  • Exclusão de mensagem
  • Indicador de digitação
  • Atividade do evento
  • Vários anexos, incluindo cartões adaptáveis
  • Dados do canal do bot

As próximas seções mostram alguns exemplos para ilustrar esses recursos.

Enviar uma mensagem de boas-vindas quando um novo usuário for adicionado ao thread

A lógica atual do Echo Bot aceita a entrada do usuário e a ecoa de volta. Se você quiser adicionar mais lógica, como responder a um evento dos Serviços de Comunicação adicionado pelo participante, copie o código a seguir e cole-o no arquivo de origem 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);
                        }
                    }
                }
            }
        }
    }
}

Enviar um cartão adaptável

Note

Os cartões adaptáveis só são suportados em casos de uso dos Serviços de Comunicação do Azure em que todos os participantes do chat são usuários dos Serviços de Comunicação do Azure e não para casos de uso de interoperabilidade do Teams.

Você pode enviar um cartão adaptável para o thread de bate-papo para aumentar o envolvimento e a eficiência. Um cartão adaptável também ajuda você a se comunicar com os usuários de várias maneiras. Você pode enviar um cartão adaptável de um bot adicionando o cartão como um anexo de atividade do bot.

Aqui está um exemplo de como enviar um cartão adaptável:

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

Obtenha exemplos de amostras para cartões adaptáveis em Amostras e modelos.

Para um usuário de chat, o canal de Chat dos Serviços de Comunicação adiciona um campo aos metadados da mensagem que indica que a mensagem tem um anexo. Nos metadados, a microsoft.azure.communication.chat.bot.contenttype propriedade é definida como azurebotservice.adaptivecard.

Aqui está um exemplo de uma mensagem de bate-papo que tem um cartão adaptável anexado:

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

Enviar uma mensagem do usuário para o bot

Você pode enviar uma mensagem de texto básica de um usuário para o bot da mesma forma que envia uma mensagem de texto para outro usuário.

No entanto, quando você enviar uma mensagem com um anexo de um usuário para um bot, adicione este sinalizador aos metadados do Chat dos Serviços de Comunicação:

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

Para enviar uma atividade de evento de um usuário para um bot, adicione este sinalizador aos metadados do Chat dos Serviços de Comunicação:

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

As seções a seguir mostram formatos de exemplo para mensagens de bate-papo de um usuário para um bot.

Mensagem de texto simples

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

Mensagem com um anexo

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

Mensagem com atividade de evento

Uma carga útil de evento inclui todos os campos JSON no conteúdo da mensagem, exceto Name. O Name campo contém o nome do evento.

No exemplo a seguir, o nome endOfConversation do evento com a carga "{field1":"value1", "field2": { "nestedField":"nestedValue" }} útil é enviado para o 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"
}

O campo microsoft.azure.communication.chat.bot.contenttype de metadados é necessário apenas em uma mensagem enviada de um usuário para um bot.

Campos de atividade de bot suportados

As seções a seguir descrevem campos de atividade de bot suportados para fluxos de bot para usuário e fluxos de usuário para bot.

Fluxo de bot para usuário

Os seguintes campos de atividade de bot são suportados para fluxos de bot para usuário.

Activities

  • Message
  • Typing

Campos de atividade da mensagem

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (Convertido em Serviços de SenderDisplayNameComunicação .)
  • ChannelData (Convertido em Serviços Chat Metadatade Comunicação . Se quaisquer ChannelData valores de mapeamento forem objetos, eles serão serializados no formato JSON e enviados como uma cadeia de caracteres.)

Fluxo de usuário para bot

Esses campos de atividade de bot são suportados para fluxos de usuário para bot.

Atividades e domínios

  • Message

    • Id (ID da mensagem do chat dos Serviços de Comunicação)
    • TimeStamp
    • Text
    • Attachments

  • Atualização da conversação

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Atualização da mensagem

    • Id (ID de mensagem de chat dos Serviços de Comunicação atualizado)
    • Text
    • Attachments

  • Exclusão de mensagem

    • Id (ID da mensagem de chat dos Serviços de Comunicação excluídos)

  • Event

    • Name
    • Value

  • Typing

Outros domínios comuns

  • Recipient.Id e Recipient.Name (ID de usuário e nome de exibição do Chat dos Serviços de Comunicação)
  • From.Id e From.Name (ID de usuário e nome de exibição do Chat dos Serviços de Comunicação)
  • Conversation.Id (ID do thread de bate-papo dos Serviços de Comunicação)
  • ChannelId (Chat dos Serviços de Comunicação se estiver vazio)
  • ChannelData (Metadados de mensagens de chat dos Serviços de Comunicação)

Padrões de transferência de bots

Às vezes, um bot não entende uma pergunta ou não consegue responder a uma pergunta. Um cliente pode pedir no chat para estar conectado a um agente humano. Nesses cenários, o thread de bate-papo deve ser passado do bot para um agente humano. Você pode projetar seu aplicativo para fazer a transição de uma conversa de um bot para um humano.

Manipulando a comunicação entre bots

Em alguns casos de uso, dois bots precisam ser adicionados ao mesmo thread de bate-papo para fornecer serviços diferentes. Nesse cenário, talvez seja necessário garantir que um bot não envie respostas automatizadas para as mensagens de outro bot. Se não for tratada corretamente, a interação automatizada dos bots entre si pode resultar em um loop infinito de mensagens.

Você pode verificar a identidade do usuário dos Serviços de Comunicação de um remetente de mensagem na propriedade da From.Id atividade. Verifique se ele pertence a outro bot. Em seguida, execute a ação necessária para evitar um fluxo de comunicação entre bots. Se esse tipo de cenário resultar em grandes volumes de chamadas, o canal de Chat dos Serviços de Comunicação limitará as solicitações e um bot não poderá enviar e receber mensagens.

Saiba mais sobre os limites de aceleração.

Troubleshoot

As seções a seguir descrevem maneiras de solucionar problemas de cenários comuns.

Não é possível adicionar um canal de chat

No portal do desenvolvedor do Microsoft Bot Framework, vá para Configuração>Mensagens do Bot para verificar se o ponto de extremidade está definido corretamente.

Bot recebe uma exceção proibida ao responder a uma mensagem

Verifique se o ID e a senha do aplicativo Microsoft do bot estão salvos corretamente no arquivo de configuração do bot carregado no aplicativo Web.

O Bot não pode ser adicionado como participante

Verifique se a ID dos Serviços de Comunicação do bot é usada corretamente quando uma solicitação é enviada para adicionar um bot a um thread de chat.

Próximos passos

Experimente o aplicativo de demonstração do bot de bate-papo para um bate-papo 1:1 entre um usuário de bate-papo e um bot por meio do componente BotFramework WebChat UI.

Para obter mais informações sobre como adicionar um bot OpenAI, consulte Integrar um bot OpenAI com bate-papo.

  • Last updated on