Mensagens proativas

Importante

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

Uma mensagem proativa é qualquer mensagem enviada por um bot que não esteja em resposta a uma solicitação de um usuário. Isso pode incluir mensagens, como:

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

Importante

Atualmente, os bots estão disponíveis na Nuvem da Comunidade Governamental (GCC) e no GCC-High, mas não no Departamento de Defesa (DOD).

Para mensagens proativas, os bots devem usar os seguintes pontos de extremidade para ambientes de nuvem governamentais:

• GCC: https://smba.infra.gcc.teams.microsoft.com/gcc.
• GCCH: https://smba.infra.gov.teams.microsoft.us/gcch.

Para que seu bot envie uma mensagem proativa a um usuário, chat em grupo ou equipe, ele precisa ter acesso 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 para enviar por push aplicativos para equipes e usuários no seu locatário. Se for um usuário, você deve ter o aplicativo instalado ou ser um membro da 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 tópico 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, 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 trechos de código na seção exemplos são para criar uma conversa individual. Para obter links para concluir exemplos de trabalho de conversas individuais e grupos ou canais, confira o exemplo de código.

Para usar mensagens proativas efetivamente, confira práticas recomendadas para mensagens proativas. Para determinados cenários, você deve instalar proativamente seu aplicativo usando o Graph. Os trechos de código na seção exemplos são para criar uma conversa individual. Para obter exemplos de trabalho completos de conversas individuais e grupos ou canais, confira o exemplo de código.

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

É necessário ter a ID correta para criar uma nova conversa ou tópico de conversa em um canal. Você pode receber ou recuperar essa ID das seguintes formas:

• Quando seu aplicativo é instalado em qualquer contexto específico, você recebe uma atividade onMembersAdded.
• Quando um novo usuário é adicionado a um contexto em que seu aplicativo está instalado, você recebe uma atividade onMembersAdded.
• 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.
• Todas as atividades que seu bot recebe devem conter as informações necessárias.

Independentemente de como você obter as informações, é necessário armazenar a tenantId e a userId ou a 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.

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. No entanto, seu bot deve ser instalado na equipe antes de poder enviar uma mensagem proativa para um canal.

Depois de ter as informações do usuário ou do canal, você deve criar a conversa.

Criar a conversa

Você deve criar a conversa se ela não existir ou se não souber o conversationId. Você só deve criar a conversa uma vez e armazenar o valor conversationId ou o objeto conversationReference.

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

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. Você deve definir os conversationParameters corretamente para enviar sua mensagem com êxito. Confira a seção exemplos ou use um dos exemplos listados na seção exemplo de código.

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:

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 as mensagens proativas são usadas para enviar uma mensagem de boas-vindas a um usuário, não precisa haver contexto para os usuários receberem essa mensagem. Essa também é a primeira vez que os usuários interagem com seu aplicativo. É uma oportunidade para criar uma boa primeira impressão. As mensagens de boas-vindas ideais devem incluir:

• Por que um usuário está recebendo a 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.

• O que você oferece? Os usuários devem ser capazes de identificar o que eles podem fazer com seu aplicativo e qual valor você pode agregar a eles.

• O que eles devem fazer a seguir? Convide usuários a experimentar um comando ou interagir com seu aplicativo. Mensagens de boas-vindas ruins podem levar os usuários a bloquear seu bot. Escreva até o ponto e limpe as mensagens de boas-vindas. Repita as mensagens de boas-vindas se elas não estiverem tendo o efeito desejado.

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. Verifique se os usuários têm uma compreensão clara do motivo pelo qual receberam uma notificação. As mensagens de notificação consideradas boas geralmente incluem o seguinte:

• 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 executou a açã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? Forneça um caminho para que os usuários optem por não receber notificações adicionais.

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 em no catálogo de aplicativos da sua organização ou na Loja de aplicativos do Teams.

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

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

C#

[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)
        {
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, conversationReference, 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://aka.ms/BotTrustServiceUrl
        await turnContext.SendActivityAsync("proactive hello");
    }
}

TypeScript

async messageAllMembersAsync(context) {
    const members = await this.getPagedMembers(context);

    members.forEach(async (teamMember) => {
        const message = MessageFactory.text('Hello ${ teamMember.givenName } ${ teamMember.surname }. I\'m a Teams conversation bot.');

        var ref = TurnContext.getConversationReference(context.activity);
        ref.user = teamMember;

        await context.adapter.createConversation(ref,
            async (t1) => {
                const ref2 = TurnContext.getConversationReference(t1.activity);
                await t1.adapter.continueConversation(ref2, async (t2) => {
                    await t2.sendActivity(message);
                });
            });
    });

    await context.sendActivity(MessageFactory.text('All messages have been sent.'));
}

Python

async def _message_all_members(self, turn_context: TurnContext):
    team_members = await self._get_paged_members(turn_context)

    for member in team_members:
        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
        )

    await turn_context.send_activity(
        MessageFactory.text("All messages have been sent")
    )

JSON

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
Noções básicas de conversa do Teams	Demonstra as noções básicas de conversas no Teams, incluindo o envio de mensagens individuais proativas.	View	View	View
Iniciar novo tópico em um canal	Demonstra a criação de um novo tópico em um canal.	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

Exemplo de código adicional

Exemplos de código de mensagens proativas do Teams

Guias passo a passo

Siga o guia passo a passo, que ajuda você a enviar uma mensagem proativa de um bot.

Próxima etapa

Formatar suas mensagens de bot

Confira também

• Exemplos de código de mensagens proativas do Teams
• Canais e conversas de chat em grupo com um bot do Microsoft Teams
• Responder à ação de envio do módulo de tarefas
• Enviar notificações proativas aos usuários