Mensagens proativas

  • Artigo

Importante

Os exemplos de código nesta seção são baseados na versão 4.6 e versões posteriores do SDK do Bot Framework. Se você estiver procurando documentação para versões anteriores, consulte a seção bots – v3 SDK na pasta SDKs Herdados da documentação.

Uma mensagem proativa é qualquer mensagem enviada por um bot que não responde a uma solicitação de um usuário. Esta mensagem pode incluir conteúdo, como:

  • Mensagem de boas-vindas
  • Notificações
  • Mensagens agendadas

Importante

Para enviar uma mensagem proativa para um usuário, um chat em grupo ou uma equipe, seu bot deve ter o acesso necessário para enviar a mensagem. O aplicativo que contém seu bot deve ser instalado primeiro onde houver um chat em grupo ou equipe.

Você pode instalar proativamente seu aplicativo usando o Microsoft Graph em uma equipe, se necessário, ou usar uma política de aplicativo personalizada para instalar um aplicativo em suas equipes e para usuários da organização. Para determinados cenários, você deve instalar proativamente seu aplicativo usando o Graph. Para um usuário receber mensagens proativas, instale o aplicativo para o usuário ou faça do usuário uma parte de uma equipe na qual o aplicativo está instalado.

Enviar uma mensagem proativa é diferente de enviar uma mensagem normal. Não há nenhum ativo turnContext a ser usado como resposta. Você deve criar a conversa antes de enviar a mensagem. Por exemplo, um novo chat individual ou um novo thread de conversa em um canal. Não é possível criar um novo chat em grupo ou um novo canal em uma equipe com mensagens proativas.

Para enviar uma mensagem proativa, siga estas etapas:

  1. Obtenha a ID do usuário Microsoft Entra, ID do usuário, ID da equipe ou ID do canal, se necessário.
  2. Crie a conversa, se necessário.
  3. Obtenha a ID da conversa.
  4. Envie a mensagem.

Os snippets de código na seção exemplos são para criar uma conversa individual. Para obter links para exemplos para conversas um-a-um e mensagens de grupo ou canais, consulte exemplo de código. Para usar mensagens proativas de forma eficaz, consulte as melhores práticas para mensagens proativas.

Obter a ID do usuário Microsoft Entra, a ID do usuário, a ID da equipe ou a ID do canal

Você pode criar uma nova conversa com um usuário ou um thread de conversa em um canal e deve ter a ID correta. Você pode receber ou recuperar essa ID usando qualquer uma das seguintes maneiras:

  • Quando seu aplicativo é instalado em um contexto específico, você recebe uma onMembersAdded atividade.
  • Quando um novo usuário é adicionado a um contexto em que seu aplicativo está instalado, você recebe uma atividade onMembersAdded.
  • Cada evento que o bot recebe contém as informações necessárias, que você pode obter do contexto do bot (objeto TurnContext).
  • Você pode recuperar a lista de canais em uma equipe onde seu aplicativo está instalado.
  • Você pode recuperar a lista de membros de uma equipe onde seu aplicativo está instalado.

Independentemente de como você obtém as informações, armazene e tenantId armazene o userId, ou channelId para criar uma nova conversa. Você também pode usar a teamId para criar um novo tópico de conversa no canal geral ou padrão de uma equipe. Verifique se o bot está instalado na equipe antes de enviar uma mensagem proativa para um canal.

  • O aadObjectId é exclusivo para o usuário e pode ser recuperado usando a API do grafo para criar uma nova conversa no chat pessoal. Verifique se o bot está instalado no escopo pessoal antes de enviar uma mensagem proativa. Se o bot não estiver instalado em um escopo pessoal ao enviar uma mensagem proativa usando o aadObjectId, o bot retornará um 403 erro com ForbiddenOperationException a mensagem.

  • A userId é exclusiva da ID do bot e de um usuário específico. Não é possível reutilizar a userId entre bots.

  • O channelId é global.

Create a conversa, depois de ter as informações do usuário ou do canal.

Observação

O envio de mensagens proativas usando aadObjectId só tem suporte no escopo pessoal.

Criar a conversa

Você pode criar a conversa se ela não existir ou não conhecer o conversationId. Create a conversa apenas uma vez e armazene o valor ou conversationReference o conversationId objeto.

Para criar a conversa, você precisa de um aadObjectId ou userId, tenantIde serviceUrl.

Para serviceUrl, use o valor de uma atividade de entrada disparando o fluxo ou uma das URLs de serviço globais. Se o serviceUrl não estiver disponível de uma atividade de entrada que dispara o cenário proativo, use os seguintes pontos de extremidade de URL globais:

  • Público: https://smba.trafficmanager.net/teams/
  • GCC: https://smba.infra.gcc.teams.microsoft.com/teams
  • GCCH: https://smba.infra.gov.teams.microsoft.us/teams
  • DOD: https://smba.infra.dod.teams.microsoft.us/teams

Para obter um exemplo de código, consulte a chamada CreateConversationAsync no exemplo.

Você pode obter a conversa quando o aplicativo é instalado pela primeira vez. Depois que a conversa for criada, obtenha a ID da conversa. O conversationId está disponível nos eventos de atualização da conversa.

A ID da conversa é exclusiva para cada bot em um canal específico, mesmo em um ambiente multilocatário. Essa ID garante que as mensagens do bot sejam direcionadas para o canal apropriado e não interrompam com outros bots ou canais dentro das mesmas ou em organizações diferentes.

Se você não tiver o conversationId, poderá instalar proativamente seu aplicativo usando o Graph para obter o conversationId.

Obter a ID da conversa

Use o objeto conversationReference ou a conversationId e tenantId para enviar a mensagem. É possível obter essa ID criando a conversa ou armazenando-a de qualquer atividade enviada a você desse contexto. Armazene essa ID para referência.

Depois de obter as informações de endereço apropriadas, é possível enviar sua mensagem.

Enviar a mensagem

Agora que você tem as informações de endereço corretas, pode enviar sua mensagem. Se estiver usando o SDK, deverá usar o método continueConversation e a conversationId e tenantId para fazer uma chamada direta à API. Para enviar sua mensagem, defina o conversationParameters. Confira a seção exemplos ou use um dos exemplos listados na seção exemplo de código.

Observação

O Teams não dá suporte ao envio de mensagens proativas usando o email ou o Nome da Entidade de Usuário (UPN).

Depois de enviada a mensagem proativa, você deverá seguir essas práticas recomendadas ao enviar mensagens proativas para obter uma melhor troca de informações entre os usuários e o bot.

Confira o vídeo a seguir para saber como enviar mensagens proativas de bots:



Entender quem bloqueou, silenciou ou desinstalou um bot

Como desenvolvedor, você pode criar um relatório para entender quais usuários da sua organização bloquearam, silenciaram ou desinstalaram um bot. Essas informações podem ajudar os administradores da sua organização a transmitir mensagens em toda a organização ou impulsionar o uso do aplicativo.

Usando o Teams, você pode enviar uma mensagem proativa ao bot para verificar se um usuário bloqueou ou desinstalou um bot. Se o bot estiver bloqueado ou desinstalado, o Teams retornará um código de 403 resposta com um subCode: MessageWritesBlocked. Essa resposta indica que a mensagem enviada pelo bot não é entregue ao usuário.

O código de resposta é enviado por usuário e inclui a identidade do usuário. Você pode compilar os códigos de resposta para cada usuário ao lado de sua identidade para criar um relatório de todos os usuários que bloquearam o bot.

Um exemplo de um código de resposta 403 está abaixo.


HTTP/1.1 403 Forbidden

Cache-Control: no-store, must-revalidate, no-cache

 Pragma: no-cache

 Content-Length: 196

 Content-Type: application/json; charset=utf-8

 Server: Microsoft-HTTPAPI/2.0

 Strict-Transport-Security: max-age=31536000; includeSubDomains

 MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0

 ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0

 Date: Tue, 29 Mar 2022 17:34:33 GMT

{"errorCode":209,"message":"{\r\n  \"subCode\": \"MessageWritesBlocked\",\r\n  \"details\": \"Thread is blocked from message writes.\",\r\n  \"errorCode\": null,\r\n  \"errorSubCode\": null\r\n}"}

Práticas recomendadas para mensagens proativas

Enviar mensagens proativas aos usuários é uma maneira eficaz de se comunicar com seus usuários. No entanto, da perspectiva do usuário, a mensagem aparece espontaneamente. Se houver uma mensagem de boas-vindas, será a primeira vez que eles interagirão com seu aplicativo. É importante usar essa funcionalidade e fornecer as informações completas ao usuário para entender a finalidade dessa mensagem.

Mensagem de boas-vindas

Quando mensagens proativas são usadas para enviar uma mensagem de boas-vindas a um usuário, não há contexto para o motivo pelo qual o usuário recebe a mensagem. Além disso, essa é a primeira interação do usuário com seu aplicativo. É uma oportunidade para criar uma boa primeira impressão. Uma boa experiência do usuário garante uma melhor adoção do aplicativo. Mensagens de boas-vindas ruins podem levar os usuários a bloquear seu aplicativo. Escreva uma mensagem de boas-vindas clara e itere na mensagem de boas-vindas se ela não estiver tendo o efeito desejado.

Uma boa mensagem de boas-vindas pode incluir o seguinte:

  • Motivo da mensagem – Deve ficar claro para o usuário por que ele está recebendo a mensagem. Se seu bot foi instalado em um canal e você enviou uma mensagem de boas-vindas para todos os usuários, informe a eles em qual canal ele foi instalado e quem o instalou.

  • Sua oferta – os usuários devem ser capazes de identificar o que podem fazer com seu aplicativo e qual valor você pode trazer para eles.

  • Próximas etapas – os usuários devem entender as próximas etapas. Por exemplo, convide os usuários para experimentar um comando ou interagir com seu aplicativo.

Mensagens de notificação

Para enviar notificações usando mensagens proativas, verifique se os usuários têm um caminho claro para executar ações comuns com base em sua notificação. Se as ações do usuário forem necessárias em um aplicativo de guia, use notificações de feed de atividades em vez de um bot. Verifique se os usuários têm uma compreensão clara do motivo pelo qual receberam uma notificação. As boas mensagens de notificação geralmente incluem os seguintes itens:

  • O que está acontecendo? Uma indicação clara do que aconteceu para causar a notificação.

  • Qual foi o resultado? Deve ser claro, qual item está atualizado para receber a notificação.

  • Quem ou o que a disparou? Quem ou o que tomou medidas, o que fez com que a notificação fosse enviada.

  • O que os usuários podem fazer em resposta? Facilite para que seus usuários realizem ações com base nas suas notificações.

  • Como os usuários podem optar por sair? Você deve fornecer um caminho para que os usuários optem por não receber mais notificações.

Para enviar mensagens para um grande grupo de usuários, por exemplo, para sua organização, instale proativamente seu aplicativo usando o Graph.

Mensagens agendadas

Ao usar mensagens proativas para enviar mensagens agendadas aos usuários, verifique se o fuso horário está atualizado com o fuso horário deles. Isso garante que as mensagens sejam entregues aos usuários no momento relevante. As mensagens agendadas geralmente incluem:

  • Por que o usuário está recebendo a mensagem? Facilite para que seus usuários entendam o motivo pelo qual estão recebendo a mensagem.

  • O que o usuário pode fazer a seguir? Os usuários podem executar as ações necessárias com base no conteúdo da mensagem.

Instalar proativamente seu aplicativo usando o Graph

Envie mensagens proativas a usuários que anteriormente não instalaram ou interagiram com seu aplicativo. Por exemplo, você deseja usar o comunicador da empresa para enviar mensagens para toda a organização. Nesse caso, você pode usar a API do Graph para instalar proativamente seu aplicativo aos usuários. Armazene em cache os valores necessários do evento conversationUpdate que seu aplicativo recebe após a instalação.

Você só pode instalar aplicativos que estão no catálogo de aplicativos organizacionais ou na Microsoft Teams Store.

Confira instalar aplicativos para usuários na documentação do Graph e instalação proativa de bot e mensagens no Teams com o Graph. Também há um exemplo de framework do Microsoft .NET na plataforma GitHub.

Exemplos

Certifique-se de autenticar e ter um token de portador antes de criar uma nova conversa usando a API REST. Veja a seguir a API REST para criar uma conversa em contextos diferentes:

  • A API REST para criar uma conversa em um chat individual.

  • API REST para criar uma conversa em um canal.

  • API REST para Atualizar mensagem na conversa: para atualizar uma atividade existente dentro de uma conversa, inclua conversationId e activityId no ponto de extremidade da solicitação. Para concluir esse cenário, você deve armazenar em cache a ID da atividade retornada pela pós-chamada original.

    PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}

    
{
    "type": "message",
    "text": "This message has been updated"
}

    Para atualizar uma atividade existente em uma conversa, inclua o conversationId e activityId no ponto de extremidade de solicitação. Para concluir esse cenário, você deve armazenar em cache o activity ID retornado pela chamada de postagem original. Se a chamada for bem-sucedida, a API retornará o seguinte objeto de resposta.

    {
    "id": "{{activityID}}"
}

Exemplos

O código a seguir mostra como enviar mensagens proativas:

[Route("api/notify")]
[ApiController]
public class NotifyController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly string _appId;
    private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

    public NotifyController(IBotFrameworkHttpAdapter adapter, IConfiguration configuration, ConcurrentDictionary<string, ConversationReference> conversationReferences)
    {
        _adapter = adapter;
        _conversationReferences = conversationReferences;
        _appId = configuration["MicrosoftAppId"] ?? string.Empty;
    }

    public async Task<IActionResult> Get()
    {
        foreach (var conversationReference in _conversationReferences.Values)
        {
            var newReference = new ConversationReference()
            {
                Bot = new ChannelAccount()
                {
                    Id = conversationReference.Bot.Id
                },
                Conversation = new ConversationAccount()
                {
                    Id = conversationReference.Conversation.Id
                },
                ServiceUrl = conversationReference.ServiceUrl,
            };

            // Sends a proactive message from the bot to a conversation.
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, newReference, BotCallback, default(CancellationToken));
        }
        
        // Let the caller know proactive messages have been sent.
        return new ContentResult()
        {
            Content = "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,
        };
    }

    private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
    {
        // If you encounter permission-related errors when sending this message, see
        // https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp#avoiding-401-unauthorized-errors
        // Sends an activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Exemplo de um snippet de código para demonstrar a criação de referência de conversa.

 var newReference = new ConversationReference()
        {
            Bot = new ChannelAccount()
            {
                Id = conversationReference.Bot.Id
            },
            Conversation = new ConversationAccount()
            {
                Id = conversationReference.Conversation.Id
            },
            ServiceUrl = conversationReference.ServiceUrl,
        };

Exemplo de código

A tabela a seguir fornece um exemplo de código simples que incorpora o fluxo básico de conversação em um aplicativo do Teams e como criar um novo thread de conversa em um canal no Teams:

Nome de exemplo Descrição .NET Node.js Python Manifesto
Noções básicas de conversa do Teams Este aplicativo de exemplo mostra como usar diferentes eventos de conversa de bot disponíveis na estrutura do bot v4 para escopo pessoal e de equipes. View View View View
Iniciar novo tópico em um canal Este exemplo mostra como iniciar um thread em um canal específico da Equipe usando o Bot Framework v4. View View View View
Instalação proativa do aplicativo e envio de notificações proativas Este exemplo mostra como você pode usar a instalação proativa do aplicativo para usuários e enviar notificações proativas chamando as APIs do Microsoft Graph. View Exibir NA View
Mensagens proativas Este é um exemplo que mostra como salvar as informações de referência de conversa do usuário para enviar mensagens de lembrete proativas usando Bots. View View NA

Mais exemplo de código de mensagens proativas

Próxima etapa

Formatar suas mensagens de bot

Confira também