Adicionar um bot ao aplicativo de chat

2025-05-12

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 usando o SDK de Chat dos Serviços de Comunicação.

Esse artigo descreve como:

Criar e implantar um bot no Azure
Obter um recurso de Serviços de Comunicação
Habilitar o Canal de Chat dos Serviços de Comunicação para o bot
Criar um aplicativo de chat e adicionar o bot como um participante
Explorar mais recursos para o seu bot

Pré-requisitos

Uma conta Azure e uma assinatura ativa. Crie uma conta gratuitamente.
Visual Studio 2019 ou posterior.
A versão mais recente do .NET Core. Neste início rápido, usamos o .NET Core 3.1. Instale a versão que corresponde à sua instância do Visual Studio, de 32 ou 64 bits.
Estrutura de bot SDK

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 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 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. Este exemplo usa um bot multitenant.

Para configurar um bot de locatário único ou de identidade gerenciada, 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 que são atribuídas ao bot quando implantados. 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 Construtor de Bot para seu cenário ou usar o SDK do Construtor de Bots 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 endpoint manipula todas as mensagens enviadas para o bot.

Para criar o aplicativo de 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:

No portal, selecione Criar um recurso. Na caixa de pesquisa, insira aplicativo Web. Selecione o azulejo Aplicativo Web.
Em Criar Aplicativo Web, selecione ou insira detalhes para o aplicativo, incluindo a região em que você deseja implantar o aplicativo.
Selecione Examinar + Criar para validar a implantação e examinar os detalhes da implantação. Em seguida, selecione Criar.
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.

Criar um endpoint de mensagens para o bot

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

No portal do Azure, acesse o recurso do serviço de Bot do Azure. No menu de recursos, selecione Configuração.
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.
Clique em Salvar.

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:

Use o Git para clonar este repositório do GitHub:

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

No Visual Studio, abra o projeto do Echo Bot.
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.
No Visual Studio, no Gerenciador de Soluções, clique com o botão direito do mouse no projeto EchoBot e selecione Publicar:
Selecione Novo para criar um novo perfil de publicação. Em Destino, selecione Azure:

Para o destino específico, selecione Serviço de Aplicativo do Azure:
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.

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:

Conclua as etapas para criar um recurso dos Serviços de Comunicação.
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

Ao ter um recurso dos Serviços de Comunicação, você pode configurar um canal de Serviços de Comunicação dentro do recurso de bot. Nesse processo, uma ID de usuário é gerada para o bot.

No portal do Azure, acesse o recurso do serviço de Bot do Azure. No menu recurso, selecione Canais. Na lista de canais disponíveis, selecione Serviços de Comunicação do Azure – Chat.
Selecione Conectar para ver uma lista de recursos dos Serviços de Comunicação disponíveis em sua assinatura.
No painel Nova Conexão, selecione o recurso de chat dos Serviços de Comunicação e, em seguida, selecione Aplicar.
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.

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#

Execute o seguinte comando para criar um aplicativo C#:
```
dotnet new console -o ChatQuickstart
```
Altere o diretório para a nova pasta do aplicativo e use o dotnet build comando para compilar seu 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 o endpoint dos Serviços de Comunicação e o token de acesso do usuário que você gerou 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 instruções a seguir.

Copie o seguinte código e cole-o no arquivo de origem do 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 thread 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 GetChatThreadClient método retorna um cliente thread para um thread 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 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 de uma conversa de chat

Você pode obter mensagens de chat consultando o método GetMessages no cliente de thread de bate-papo 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 Hello World.

Você pode usar o JavaScript ou os SDKs móveis do Azure para assinar notificações de mensagem 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 o thread de chat, exclua o thread:

chatClient.DeleteChatThread(threadId);

Implantar o aplicativo de chat em C#

Para implantar o aplicativo de chat:

No Visual Studio, abra o projeto de chat.
Clique com o botão direito do mouse no projeto ChatQuickstart e selecione Publicar:
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, pode continuar a brincar com as várias atividades necessárias para os cenários de negócios que talvez seja necessário 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 adaptativo a partir 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 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 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 com suporte

As seções a seguir descrevem os campos de atividade de bot com suporte para fluxos de bot-para-usuário e 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 de chat dos Serviços de Comunicações)

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, 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 a Configuração>Bot Messaging para verificar se o ponto de extremidade está 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 1:1 entre um usuário de chat e um bot por meio do componente de interface do usuário do WebChat do BotFramework.

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

Compartilhar via