Início Rápido: Adicionar um bot ao seu aplicativo de chat

  • Artigo

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, disponível no Serviço de Bot do Azure. Neste início rápido, você criará um bot usando o SDK do BotFramework. Em seguida, integre o bot a um aplicativo de chat criado com o SDK de Chat dos Serviços de Comunicação.

Neste guia de início rápido, você aprende a:

Pré-requisitos

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 a ID e a senha do aplicativo do bot
  • Criar um aplicativo Web para manter a lógica do bot
  • Criar um ponto de extremidade de mensagens para o bot

Criar um recurso do Serviço de Bot do Azure

Primeiro, use o portal do Azure para criar um recurso do Serviço de Bot do Azure. O canal de Chat dos Serviços de Comunicação também dá suporte a bots de identidade gerenciada, de locatário único e de vários locatários. Para fins deste início rápido, usaremos um bot multilocatário.

Para configurar um bot de identidade gerenciada ou de locatário único, examine as informações de identidade do bot.

Para um bot de identidade gerenciada, talvez seja necessário atualizar a identidade do serviço de bot.

Obter a ID e a senha do aplicativo do bot

Em seguida, obtenha a ID do aplicativo da Microsoft e a senha atribuídas ao bot quando ele for 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, revise exemplos do Bot Builder para seu cenário ou use 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 controlador de aplicativo Web do aplicativo de bot exponha um ponto de extremidade no formulário /api/messages. O ponto de extremidade manipula todas as mensagens enviadas para o bot.

Para criar o aplicativo bot, use a CLI do Azure para criar um recurso de 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, insira aplicativo Web. Selecione o bloco Aplicativo Web.

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

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

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

  3. Selecione Examinar + Criar para validar a implantação e examinar os detalhes da implantação. Em seguida, selecione Criar.

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

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

Criar um ponto de extremidade de mensagens para o bot

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

  1. No portal do Azure, acesse o recurso de Bot do Azure. No menu de recursos, selecione Configuração.

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

  3. Selecione Salvar.

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

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 do 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. Cole a ID do aplicativo Microsoft e a senha do aplicativo copiadas anteriormente:

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

    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:

    Screenshot that shows publishing your web app from Visual Studio.

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

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

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

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

  6. Na configuração de implantação, selecione o aplicativo Web nos resultados exibidos após entrar em sua conta do Azure. Para concluir o perfil, selecione Concluir e, em seguida, selecione Publicar para iniciar a implantação.

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

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

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

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

  2. Crie um usuário dos Serviços de Comunicação e emita um token de acesso do usuário. Defina o escopo como chat. Copie a cadeia de caracteres de token e a cadeia de caracteres de ID de usuário.

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

Com um recurso dos Serviços de Comunicação, é possível configurar um canal dos Serviços de Comunicação no recurso de bot. Nesse processo, uma ID de usuário é gerada para o bot.

  1. No portal do Azure, acesse o recurso de Bot do Azure. No menu recurso, selecione Canais. Na lista de canais disponíveis, selecione Serviços de Comunicação do Azure – Chat.

    Screenshot that shows opening the Communication Services Chat channel.

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

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

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

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

  4. Quando os detalhes do recurso são verificados, uma ID de bot é mostrada na coluna de Bot de Serviços de Comunicação do Azure. Use a ID do bot para representar o bot em uma conversa de chat usando a API AddParticipant do Chat dos Serviços de Comunicação. Depois de adicionar o bot a um chat como participante, o bot começa a receber atividades relacionadas ao chat e pode responder na conversa do chat.

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

Criar um aplicativo de chat e adicionar o bot como um participante

Agora que você tem a ID dos Serviços de Comunicação do bot, poderá criar uma conversa de chat com o bot como um participante.

Criar um aplicativo em C#

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

    dotnet new console -o ChatQuickstart

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

    cd ChatQuickstart
dotnet build

Instalar 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 seu ponto de extremidade dos Serviços de Comunicação e o token de acesso do usuário gerado anteriormente. Use a classe CommunicationIdentityClient do SDK de Identidade para criar um usuário e emitir um token a ser passado para o cliente de chat. Os tokens de acesso podem ser gerados no portal usando as instruções a seguir.

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 uma conversa de chat com o bot

Use o método createChatThread em chatClient para criar uma conversa 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 conversa de chat

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

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

Enviar uma mensagem para uma conversa de chat

Para usar SendMessage para enviar uma mensagem para uma conversa:

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

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Receber mensagens de chat de uma conversa de chat

Obtenha mensagens de chat sondando o método GetMessages no cliente da conversa de chat em intervalos definidos:

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 "Olá, Mundo".

Use o 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 thread de chat

Quando terminar de usar a conversa de chat, exclua a conversa:

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:

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

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

Mais coisas que você pode fazer com um bot

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

  • Atualização de conversa
  • Atualização de mensagem
  • Exclusão de mensagem
  • Indicador de digitação
  • Atividade de evento
  • Vários anexos, incluindo cartões adaptáveis
  • Dados do canal de 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 à conversa

A lógica do Echo Bot atual 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 por um participante, copie o código a seguir e cole-o no arquivo de origemEchoBot.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

Observação

Os cartões adaptáveis só têm suporte 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.

Envie um cartão adaptável para a conversa de chat 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. Envie um cartão adaptável de um bot adicionando o cartão como um anexo de atividade de 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 conteúdos para cartões adaptáveis em Exemplos 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 propriedade microsoft.azure.communication.chat.bot.contenttype é definida como azurebotservice.adaptivecard.

Aqui está um exemplo de uma mensagem de chat 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

Enviar uma mensagem de texto básica de um usuário para o bot da mesma maneira que envia uma mensagem de texto para outro usuário.

No entanto, ao enviar uma mensagem que tenha um anexo de um usuário para um bot, adicione esse 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 de 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 chat 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 uma atividade de evento

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

No exemplo a seguir, o nome do evento endOfConversation com o conteúdo "{field1":"value1", "field2": { "nestedField":"nestedValue" }} é 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 de metadados microsoft.azure.communication.chat.bot.contenttype é necessário apenas em uma mensagem enviada de um usuário para um bot.

Campos de atividade de bot com suporte

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

Fluxo do bot para o usuário

Os campos de atividade de bot a seguir têm suporte para fluxos de bot para usuário.

Atividades

  • Mensagem
  • Digitação

Campos de atividade de mensagem

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

Fluxo do usuário para o bot

Esses campos de atividade de bot têm suporte para fluxos de usuário para bot.

Atividades e campos

  • Mensagem

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

  • Atualização de conversa

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Atualização de mensagem

    • Id (ID de mensagem do Chat dos Serviços de Comunicação atualizada)
    • Text
    • Attachments

  • Exclusão de mensagem

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

  • Evento

    • Name
    • Value

  • Digitação

Outros campos 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 de conversa do Chat dos Serviços de Comunicação)
  • ChannelId (Chat dos Serviços de Comunicação se estiver vazio)
  • ChannelData (metadados de mensagem do Chat dos Serviços de Comunicação)

Padrões de entrega do bot

Às vezes, um bot não entende uma pergunta ou não pode responder a uma pergunta. Um cliente pode pedir no chat para estar conectado a um agente humano. Nesses cenários, a conversa de chat deve ser transferida do bot para um agente humano. Crie o aplicativo para fazer a transição de uma conversa de um bot para uma pessoa.

Como lidar com a comunicação de bot para bot

Em alguns casos de uso, em que dois bots precisam ser adicionados à mesma conversa de chat 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 tratado corretamente, a interação automatizada dos bots entre si poderá resultar em um loop infinito de mensagens.

Verifique a identidade do usuário dos Serviços de Comunicação de um remetente de mensagem na propriedade From.Id da atividade. Verifique se ele pertence a outro bot. Em seguida, execute a ação necessária para impedir um fluxo de comunicação bot para bot. 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 restrição.

Solucionar problemas

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

Não é possível adicionar o canal do Chat

No portal do desenvolvedor do Microsoft Bot Framework, acesse aConfiguração>de Mensagens de Bot para verificar se o ponto de extremidade foi definido corretamente.

O bot recebe uma exceção proibida ao responder a uma mensagem

Verifique se a ID e a senha do aplicativo Microsoft do bot foram 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 uma conversa de chat.

Próximas etapas

Experimente o aplicativo de demonstração de chat bot para um chat individualizado entre um usuário de chat e um bot por meio do componente de interface do usuário do WebChat do BotFramework.