Partilhar via

Guia de início rápido: adicione um bot ao seu aplicativo de bate-papo

  • 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 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, você integra o bot em um aplicativo de chat criado usando o SDK de Chat dos Serviços de Comunicação.

Neste início rápido, vai aprender 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 Chat dos Serviços de Comunicação oferece suporte a bots de locatário único, bots de identidade gerenciados e bots multilocatário.

  • Para os fins deste início rápido, usaremos um multitenant bot.
  • Para configurar um single-tenant bot ou , revise managed identity as informações de identidade do bot.
  • Para um managed identity bot, talvez seja necessário atualizar a identidade do serviço de bot.

Obter o ID e a senha do aplicativo do bot

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

Criar um aplicativo bot e publicá-lo em um aplicativo Web

Para criar um bot, siga um destes procedimentos:

  • Revise exemplos do Bot Builder para seu cenário, crie um aplicativo Web e implante seu exemplo de bot nele.
  • Use o SDK do Bot Builder para criar e publicar um bot em um aplicativo Web.

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

Criar um aplicativo Web para manter o aplicativo bot

Para criar o aplicativo Web, 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 bloco 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 Rever + Criar para validar a implementação e rever os detalhes da implementação. Em seguida, selecione Criar.

  4. Quando o recurso do 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 Bot Application Web App Controller exponha um ponto de extremidade no formato /api/messages. O ponto de extremidade lida com todas as mensagens que são enviadas 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 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 Guardar.

Captura de tela que mostra como criar um ponto de extremidade de mensagens de bot usando o nome de 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 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 que você copiou anteriormente:

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

    Em seguida, use o Visual Studio ou o 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 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 usuário dos Serviços de Comunicação e emita um token de acesso de usuário. Certifique-se de definir o escopo para conversar. 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

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. Você pode usar a ID do bot para representar o bot em um thread de bate-papo usando 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.

Siga o início rápido 'Adicionar bate-papo ao seu aplicativo'

Siga as etapas no início rápido Adicionar bate-papo ao seu aplicativo para criar um aplicativo de bate-papo.

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

Execute o aplicativo de chat C# localmente

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

dotnet run

Você deve receber uma mensagem do bot no console que diz "Hello World".

Saída de exemplo:

1730405535010:Hello World

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

Nota

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 cargas úteis de amostra 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 uma 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.

Atividades

  • Mensagem
  • 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

  • Mensagem

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

  • Evento

    • 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.

Resolver problemas

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 Mensagens do Bot de Configuração> para verificar se o ponto de extremidade foi 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

Introdução ao chat

Você também pode querer: