Compartilhar via

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

Primeiro, use o portal do Azure para criar um recurso do Serviço de Bot do Azure. O canal de Serviços de Comunicação de Chat também dá suporte a bots de identidade gerenciada, de locatário único e de vários locatários.

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 de bot e publicá-lo em um aplicativo Web

Para criar um bot, você pode fazer um dos seguintes procedimentos:

Para este início rápido, usaremos o exemplo de Echo Bot dos exemplos do Bot Builder.

Criar um aplicativo Web para armazenar o aplicativo de bot

Para criar o aplicativo Web, 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.

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

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

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

  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.

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

Criar um ponto de extremidade de mensagens para o 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.

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. Clique em Salvar.

Captura de tela que mostra como criar um ponto de extremidade de mensagens de bot usando o nome do host do aplicativo 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 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:

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

    Em seguida, use o Visual Studio ou VS Code 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 do aplicativo Web no Visual Studio.

  5. Selecione Novo para criar um novo perfil de publicação. Em 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 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.

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

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.

    Captura de tela 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, em seguida, selecione Aplicar.

    Captura de tela que mostra como salvar o recurso do Serviço de Comunicação selecionado para criar uma nova ID de usuário dos Serviços de Comunicação.

  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.

    Captura de tela que mostra a nova ID de usuário dos Serviços de Comunicação atribuída ao 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.

Siga o guia de início rápido "Adicionar Chat ao seu aplicativo"

Siga as etapas mostradas no início rápido Adicionar Chat ao seu aplicativo para criar um aplicativo de chat.

  1. Substitua <Resource_Endpoint> pelo ponto de extremidade dos Serviços de Comunicação na etapa Obter um Recurso do Serviço de Comunicação.
  2. Substitua <Access_Token> pelo token de acesso do usuário na etapa Obter um Recurso do Serviço de Comunicação.
  3. Substitua <Access_ID> pelos bots ACS_ID na etapa Habilitar o canal de Serviços de Comunicação de Chat.

Executar o aplicativo de chat em C# localmente

Para executar o aplicativo de chat localmente, use o comando dotnet run:

dotnet run

Você deve receber uma mensagem do bot no console que diz "Olá, Mundo".

Exemplo de saída:

1730405535010:Hello World

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

Introdução ao chat

Você também pode querer: