Mensagens proativas

Artigo
06/07/2024

Importante

Os exemplos de código nesta secção baseiam-se na versão 4.6 e versões posteriores do SDK do Bot Framework. Se estiver à procura de documentação para versões anteriores, veja a secção bots – SDK v3 na pasta SDKs Legados 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, é recomendado começar com a criação do bot de notificação com JavaScript ou o exemplo de notificação de webhook recebido. Para começar, transfira o Teams Toolkit explore. Para obter mais informações, veja Documentos do Teams Toolkit.
Os bots estão disponíveis em ambientes de Cloud da Comunidade Governamental (GCC), GCC-High e Departamento de Defesa (DOD ). Para mensagens proativas, os bots têm de utilizar os seguintes pontos finais para ambientes de cloud governamentais:
- 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 enviar uma mensagem proativa a um utilizador, a uma conversa de grupo ou a uma equipa, o bot tem de 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.

Pode instalar proativamente a sua aplicação com o Microsoft Graph numa equipa, se necessário, ou utilizar uma política de aplicações personalizada para instalar uma aplicação nas suas equipas e para os utilizadores da organização. Para determinados cenários, você deve instalar proativamente seu aplicativo usando o Graph. Para que um utilizador receba mensagens proativas, instale a aplicação para o utilizador ou torne o utilizador parte de uma equipa na qual a aplicação está instalada.

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, uma nova conversa individual ou um novo tópico de conversação num 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:

Obtenha o ID de utilizador, o ID de utilizador, o ID de equipa ou o ID do canal do Microsoft Entra, se necessário.
Crie a conversa, se necessário.
Obtenha a ID da conversa.
Envie a mensagem.

Os fragmentos de código na secção de exemplos são para criar uma conversação um-para-um. Para obter ligações para exemplos de conversações um-para-um e mensagens de grupo ou de canais, consulte o exemplo de código. Para utilizar mensagens proativas de forma eficaz, veja melhores práticas para mensagens proativas.

Obter o ID de utilizador, o ID de utilizador, o ID da equipa ou o ID do canal do Microsoft Entra

Pode criar uma nova conversação com um utilizador ou um tópico de conversação num canal e tem de ter o ID correto. Pode receber ou obter este ID através de qualquer uma das seguintes formas:

Quando a sua aplicação é instalada num contexto específico, 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 pode obter a partir 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 da forma como obtém as informações, armazene e tenantId , em seguida, armazene o userIdou channelId para criar uma nova conversação. Você também pode usar a teamId para criar um novo tópico de conversa no canal geral ou padrão de uma equipe. Certifique-se de que o bot está instalado na equipa antes de poder enviar uma mensagem proativa para um canal.

O aadObjectId é exclusivo do utilizador e pode ser obtido com a graph API para criar uma nova conversação no chat pessoal. Certifique-se de que o bot está instalado no âmbito pessoal antes de poder enviar uma mensagem proativa. Se o bot não estiver instalado num âmbito pessoal ao enviar uma mensagem proativa com o aadObjectId, o bot devolve 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.

Crie a conversação depois de ter as informações do utilizador ou do canal.

Observação

O envio de mensagens proativas através aadObjectId do é suportado apenas no âmbito pessoal.

Criar a conversa

Pode criar a conversação se não existir ou se não souber o conversationId. Crie a conversação apenas uma vez e armazene o conversationId valor ou conversationReference objeto.

Para criar a conversação, precisa de um aadObjectId ou userId, tenantIde serviceUrl.

Para serviceUrl, utilize o valor de uma atividade de entrada que aciona o fluxo ou um dos URLs de serviço global. Se o serviceUrl não estiver disponível a partir de uma atividade de entrada que aciona o cenário proativo, utilize os seguintes pontos finais de URL global:

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, veja a chamada CreateConversationAsync no exemplo.

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

O ID de conversação é exclusivo para cada bot num canal específico, mesmo num ambiente multi-inquilino. Este ID garante que as mensagens do bot são direcionadas para o canal adequado e não interrompe com outros bots ou canais dentro da mesma ou em organizações diferentes.

Se não tiver o conversationId, pode instalar proativamente a sua aplicação com 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 a sua mensagem, defina .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 suporta o envio de mensagens proativas através do e-mail ou do Nome Principal de Utilizador (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:

Compreender quem bloqueou, desativou ou desinstalou um bot

Enquanto programador, pode criar um relatório para compreender que utilizadores na sua organização bloquearam, desativaram ou desinstalaram um bot. Estas informações podem ajudar os administradores da sua organização a difundir mensagens ao nível da organização ou a impulsionar a utilização de aplicações.

Com o Teams, pode enviar uma mensagem proativa ao bot para verificar se um utilizador bloqueou ou desinstalou um bot. Se o bot estiver bloqueado ou desinstalado, o Teams devolve um 403 código de resposta com um subCode: MessageWritesBlocked. Esta resposta indica que a mensagem enviada pelo bot não é entregue ao utilizador.

O código de resposta é enviado por utilizador e inclui a identidade do utilizador. Pode compilar os códigos de resposta de cada utilizador juntamente com a respetiva identidade para criar um relatório de todos os utilizadores que bloquearam o bot.

Segue-se um exemplo de um código de resposta 403.


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 existir uma mensagem de boas-vindas, marca a primeira interação com a sua aplicação. É importante usar essa funcionalidade e fornecer as informações completas ao usuário para entender a finalidade dessa mensagem.

Mensagem de boas-vindas

Quando as mensagens proativas são utilizadas para enviar uma mensagem de boas-vindas a um utilizador, não existe contexto para o motivo pelo qual o utilizador recebe a mensagem. Além disso, esta é a primeira interação do utilizador com a sua aplicação. É uma oportunidade para criar uma boa primeira impressão. Uma boa experiência de utilizador garante uma melhor adoção da aplicação. Mensagens de boas-vindas fracas podem levar os utilizadores a bloquear a sua aplicação. Escreva uma mensagem de boas-vindas clara e itere na mensagem de boas-vindas se não estiver a ter o efeito desejado.

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

Motivo da mensagem – tem de ser claro para o utilizador por que motivo está a receber 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.
A sua oferta – os utilizadores têm de conseguir identificar o que podem fazer com a sua aplicação e qual o valor que lhes pode trazer.
Passos seguintes – os utilizadores devem compreender os passos seguintes. Por exemplo, convide utilizadores para experimentar um comando ou interagir com a sua aplicação.

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 forem necessárias ações do utilizador numa aplicação de separador, utilize as notificações do 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. Geralmente, as mensagens de boas notificações 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? Tem de fornecer um caminho para os utilizadores optarem 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.

Para atualizar ou eliminar uma mensagem proativa enviada por um bot apenas de notificação:

Controle as mensagens enviadas ao armazenar os respetivos IDs de mensagens ou referências de conversação ao enviar a mensagem proativa.
Utilize UpdateActivityAsync ou DeleteActivityAsync métodos para atualizar ou eliminar a mensagem original.

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.

Só pode instalar aplicações que estejam no catálogo de aplicações 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 que autentica e tem um token de portador antes de criar uma nova conversação com a API REST. Seguem-se a API REST para criar uma conversação em diferentes contextos:

API REST para criar uma conversação numa conversa individual.
API REST para criar uma conversação num canal.
API REST para Atualizar mensagem na conversação: para atualizar uma atividade existente numa conversação, inclua o conversationId e o activityId no ponto final do pedido. 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 este cenário, tem de colocar em cache o activity ID devolvido pela chamada pós-chamada 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://video2.skills-academy.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 fragmento de código para demonstrar a criação de referência de conversação.

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


async SendNotificationToAllUsersAsync(context) {
     const TeamMembers = await TeamsInfo.getPagedMembers(context);
     let Sent_msg_Cout = TeamMembers.members.length;
     TeamMembers.members.map(async member => {
         const ref = TurnContext.getConversationReference(context.activity);
         ref.user = member;
         await context.adapter.createConversation(ref, async (context) => {
             const ref = TurnContext.getConversationReference(context.activity);
             await context.adapter.continueConversation(ref, async (context) => {
                 await context.sendActivity("Proactive hello.");
             });
         });
     });
    await context.sendActivity(MessageFactory.text("Message sent:" + Sent_msg_Cout));
}

# Send message to all members.
async def _message_all_members(self, turn_context: TurnContext):
    team_members = await self._get_paged_members(turn_context)

    for member in team_members:
        # A conversation reference for the conversation that contains this activity.
        conversation_reference = TurnContext.get_conversation_reference(
            turn_context.activity
        )

        conversation_parameters = ConversationParameters(
            is_group=False,
            bot=turn_context.activity.recipient,
            members=[member],
            tenant_id=turn_context.activity.conversation.tenant_id,
        )

        async def get_ref(tc1):
            conversation_reference_inner = TurnContext.get_conversation_reference(
                tc1.activity
            )
            return await tc1.adapter.continue_conversation(
                conversation_reference_inner, send_message, self._app_id
            )

        async def send_message(tc2: TurnContext):
            return await tc2.send_activity(
                f"Hello {member.name}. I'm a Teams conversation bot."
            )

        await turn_context.adapter.create_conversation(
            conversation_reference, get_ref, conversation_parameters
        )

    # Sends an activity to the sender of the incoming activity.
    await turn_context.send_activity(
        MessageFactory.text("All messages have been sent")
    )

POST /v3/conversations
{
  "bot": {
    "id": "28:10j12ou0d812-2o1098-c1mjojzldxcj-1098028n ",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

É preciso fornecer a ID do usuário e a ID do locatário. Se a chamada for bem-sucedida, a API retornará o seguinte objeto de resposta:

{
  "id":"a:1qhNLqpUtmuI6U35gzjsJn7uRnCkW8NiZALHfN8AMxdbprS1uta2aT-jytfIlsZR3UZeg3TsIONNInBHsdjzj3PtfHuhkxxvS1jZZ61UAbw8fIdXcNSJyTJm7YvHFOgxo"
}

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	Esta aplicação de exemplo mostra como utilizar diferentes eventos de conversação de bot disponíveis no bot framework v4 para o âmbito pessoal e de equipas.	View	View	View	View
Iniciar novo tópico em um canal	Este exemplo mostra como iniciar um thread num canal específico da Equipa com 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	View	NA	View
Mensagens Proativas	Este é um exemplo que mostra como guardar as informações de referência de conversação do utilizador para enviar uma mensagem de lembrete proativo com Bots.	View	View	NA

Mais exemplo de código de mensagens proativas

Próxima etapa

Formatar suas mensagens de bot

Compartilhar via

Mensagens proativas

Obter o ID de utilizador, o ID de utilizador, o ID da equipa ou o ID do canal do Microsoft Entra

Criar a conversa

Obter a ID da conversa

Enviar a mensagem

Compreender quem bloqueou, desativou ou desinstalou um bot

Práticas recomendadas para mensagens proativas

Mensagem de boas-vindas

Mensagens de notificação

Mensagens agendadas

Instalar proativamente seu aplicativo usando o Graph

Exemplos

Exemplos

Exemplo de código

Próxima etapa

Confira também

Recursos adicionais