Mensagens proativas para botsProactive messaging for bots

Importante

Este artigo é baseado no SDK da Estrutura de Bot v3.This article is based on the v3 Bot Framework SDK. Se você estiver procurando a documentação atual versão 4.6 ou posterior do SDK, consulte a seção de bots de conversação.If you are looking for current documentation version 4.6 or later of the SDK, see the conversational bots section.

Uma mensagem proativa é uma mensagem enviada por um bot para iniciar uma conversa.A proactive message is a message that is sent by a bot to start a conversation. Talvez você queira que seu bot inicie uma conversa por vários motivos, incluindo:You may want your bot to start a conversation for a number of reasons, including:

  • Mensagens de boas-vindas para conversas pessoais do botWelcome messages for personal bot conversations
  • Respostas a votaçõesPoll responses
  • Notificações de eventos externosExternal event notifications

Enviar uma mensagem para iniciar um novo thread de conversa é diferente de enviar uma mensagem em resposta a uma conversa existente: quando o bot inicia uma nova conversa, não há nenhuma conversa pré-existente para a postagem da mensagem.Sending a message to start a new conversation thread is different than sending a message in response to an existing conversation: when your bot starts a new a conversation, there is no pre-existing conversation to post the message to. Para enviar uma mensagem proativa, você precisa:In order to send a proactive message you need to:

  1. Decida o que você vai dizerDecide what you're going to say
  2. Obter a ID exclusiva do usuário e a ID do locatárioObtain the user's unique Id and tenant Id
  3. Enviar a mensagemSend the message

Ao criar mensagens proativas, você deve chamar e passar a URL do serviço antes de criar o que você MicrosoftAppCredentials.TrustServiceUrl usará para enviar a ConnectorClient mensagem.When creating proactive messages you must call MicrosoftAppCredentials.TrustServiceUrl, and pass in the service URL before creating the ConnectorClient you will use to send the message. Se você não fizer isso, seu aplicativo receberá uma 401: Unauthorized resposta.If you do not, your app will receive a 401: Unauthorized response. Consulte os exemplos abaixo.See the samples below.

Práticas recomendadas para mensagens proativasBest practices for proactive messaging

Enviar mensagens proativas aos usuários pode ser uma maneira muito eficaz de se comunicar com seus usuários.Sending proactive messages to users can be a very effective way to communicate with your users. No entanto, do ponto de vista deles, essa mensagem pode parecer chegar a eles completamente não prompted e, no caso de mensagens de boas-vindas, será a primeira vez que elas interagirão com seu aplicativo.However, from their perspective this message can appear to come to them completely unprompted, and in the case of welcome messages will be the first time they've interacted with your app. Dessa forma, é muito importante usar essa funcionalidade com moderação (não spam seus usuários) e fornecer informações suficientes para que eles entendam por que estão sendo mensagens.As such, it is very important to use this functionality sparingly (don't spam your users), and to provide them with enough information to let them understand why they are being messaged.

As mensagens proativas geralmente se enquadram em uma das duas categorias: mensagens de boas-vindas ou notificações.Proactive messages generally fall into one of two categories, welcome messages or notifications.

Mensagem de boas-vindasWelcome messages

Ao usar mensagens proativas para enviar uma mensagem de boas-vindas a um usuário, você deve ter em mente que, para a maioria das pessoas que recebem a mensagem, elas não terão contexto para o motivo pelo qual a estão recebendo.When using proactive messaging to send a welcome message to a user you must keep in mind that for most people receiving the message they will have no context for why they are receiving it. Essa também é a primeira vez que eles interagem com seu aplicativo; é sua oportunidade de criar uma boa primeira impressão.This is also the first time they will have interacted with your app; it is your opportunity to create a good first impression. As melhores mensagens de boas-vindas incluirão:The best welcome messages will include:

  • Por que eles estão recebendo essa mensagem.Why are they receiving this message. Deve ser muito claro para o usuário por que ele está recebendo a mensagem.It should be very clear to the user why they are receiving the message. Se o bot foi instalado em um canal e você enviou uma mensagem de boas-vindas a todos os usuários, deixe-os saber em qual canal ele foi instalado e, potencialmente, quem o instalou.If your bot was installed in a channel and you sent a welcome message to all users, let them know what channel it was installed in and potentially who installed it.
  • O que você oferece.What do you offer. O que eles podem fazer com seu aplicativo?What can they do with your app? Qual valor você pode trazer para eles?What value can you bring to them?
  • O que eles devem fazer em seguida.What should they do next. Convide-os para experimentar um comando ou interagir com seu aplicativo de alguma forma.Invite them to try out a command, or interact with your app in some way.

Mensagens de notificaçãoNotification messages

Ao usar mensagens proativas para enviar notificações, você precisa garantir que os usuários tenham um caminho claro para tomar ações comuns com base na notificação e entender claramente por que a notificação ocorreu.When using proactive messaging to send notifications you need to make sure your users have a clear path to take common actions based on your notification, and a clear understanding of why the notification occurred. As boas mensagens de notificação geralmente incluirão:Good notification messages will generally include:

  • O que aconteceu.What happened. Uma indicação clara do que aconteceu para causar a notificação.A clear indication of what happened to cause the notification.
  • O que aconteceu com.What it happened to. Deve ser claro qual item/coisa foi atualizado para causar a notificação.It should be clear what item/thing was updated to cause the notification.
  • Quem fez isso.Who did it. Quem tomou a ação que fez com que a notificação fosse enviada.Who took the action that caused the notification to be sent.
  • O que eles podem fazer sobre isso.What they can do about it. Facilita a ação dos usuários com base em suas notificações.Make it easy for your users to take actions based on your notifications.
  • Como eles podem optar. Você precisa fornecer um caminho para os usuários não receberem notificações adicionais.How they can opt out. You need to provide a path for users to opt out of additional notifications.

Obter informações de usuário necessáriasObtain necessary user information

Os bots podem criar novas conversas com um usuário individual do Microsoft Teams obtendo a ID exclusiva do usuário e a ID do locatário.Bots can create new conversations with an individual Microsoft Teams user by obtaining the user's unique ID and tenant ID. Você pode obter esses valores usando um dos seguintes métodos:You can obtain these values using one of the following methods:

Instalar proativamente seu aplicativo usando o GraphProactively install your app using Graph

Observação

A instalação proativa de aplicativos usando o graph está atualmente na versão beta.Proactively installing apps using graph is currently in beta.

Ocasionalmente, pode ser necessário enviar mensagens proativas aos usuários que não tenham instalado ou interagido com seu aplicativo anteriormente.Occasionally it may be necessary to proactively message users that have not installed or interacted with your app previously. Por exemplo, você deseja usar o comunicador da empresa para enviar mensagens para toda a sua organização.For example, you want to use the company communicator to send messages to your entire organization. Para esse cenário, você pode usar a API do Graph para instalar proativamente seu aplicativo para seus usuários e, em seguida, armazenar em cache os valores necessários do evento que seu aplicativo receberá conversationUpdate ao instalar.For this scenario you can use the Graph API to proactively install your app for your users, then cache the necessary values from the conversationUpdate event your app will receive upon install.

Você só pode instalar aplicativos que estão no catálogo de aplicativos organizacionais ou na loja de aplicativos do Teams.You can only install apps that are in your organizational app catalogue, or the Teams app store.

Consulte Instalar aplicativos para usuários na documentação do Graph para obter detalhes completos.See Install apps for users in the Graph documentation for complete details. Também há um exemplo em .NET.There is also a sample in .NET.

ExemplosExamples

Certifique-se de autenticar e ter um token de portador antes de criar uma nova conversa usando a API REST.Be sure that you authenticate and have a bearer token before creating a new conversation using the REST API.

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

Você deve fornecer a ID do usuário e a ID do locatário.You must supply the user ID and the tenant ID. Se a chamada for bem-sucedida, a API retornará com o objeto de resposta a seguir.If the call succeeds, the API returns with the following response object.

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

Essa ID é a ID de conversa exclusiva do chat pessoal.This ID is the personal chat's unique conversation ID. Armazene esse valor e reutilize-o para futuras interações com o usuário.Please store this value and reuse it for future interactions with the user.

Usando o .NETUsing .NET

Este exemplo usa o pacote NuGet Microsoft.Bot.Connector.Teams.This example uses the Microsoft.Bot.Connector.Teams NuGet package.

// Create or get existing chat conversation with user
var response = client.Conversations.CreateOrGetDirectConversation(activity.Recipient, activity.From, activity.GetTenantId());

// Construct the message to post to conversation
Activity newActivity = new Activity()
{
    Text = "Hello",
    Type = ActivityTypes.Message,
    Conversation = new ConversationAccount
    {
        Id = response.Id
    },
};

// Post the message to chat conversation with user
await client.Conversations.SendToConversationAsync(newActivity, response.Id);

Usando Node.jsUsing Node.js

var address =
{
    channelId: 'msteams',
    user: { id: userId },
    channelData: {
        tenant: {
            id: tenantId
        }
    },
    bot:
    {
        id: appId,
        name: appName
    },
    serviceUrl: session.message.address.serviceUrl,
    useAuth: true
}

var msg = new builder.Message().address(address);
msg.text('Hello, this is a notification');
bot.send(msg);

Consulte também Exemplos da Estrutura de Bot.See also Bot Framework samples.

Criar uma conversa de canalCreating a channel conversation

Seu bot adicionado pela equipe pode postar em um canal para criar uma nova cadeia de respostas.Your team-added bot can post into a channel to create a new reply chain. Se você estiver usando o Node.js SDK do Teams, use o que fornece um endereço totalmente preenchido com a ID de atividade correta e a startReplyChain() ID da conversa. Se você estiver usando C#, consulte o exemplo abaixo.If you're using the Node.js Teams SDK, use startReplyChain() which gives you a fully-populated address with the correct activity id and conversation id. If you are using C#, see the example below.

Como alternativa, você pode usar a API REST e emitir uma solicitação POST para /conversations o recurso.Alternatively, you can use the REST API and issue a POST request to /conversations resource.

Exemplo do .NET (a partir deste exemplo).NET example (from this sample)

using Microsoft.Bot.Builder.Dialogs;
using Microsoft.Bot.Connector;
using Microsoft.Bot.Connector.Teams.Models;
using Microsoft.Teams.TemplateBotCSharp.Properties;
using System;
using System.Threading.Tasks;

namespace Microsoft.Teams.TemplateBotCSharp.Dialogs
{
    [Serializable]
    public class ProactiveMsgTo1to1Dialog : IDialog<object>
    {
        public async Task StartAsync(IDialogContext context)
        {
            if (context == null)
            {
                throw new ArgumentNullException(nameof(context));
            }

            var channelData = context.Activity.GetChannelData<TeamsChannelData>();
            var message = Activity.CreateMessageActivity();
            message.Text = "Hello World";

            var conversationParameters = new ConversationParameters
            {
                  IsGroup = true,
                  ChannelData = new TeamsChannelData
                  {
                      Channel = new ChannelInfo(channelData.Channel.Id),
                  },
                  Activity = (Activity) message
            };

            MicrosoftAppCredentials.TrustServiceUrl(serviceUrl, DateTime.MaxValue);
            var connectorClient = new ConnectorClient(new Uri(activity.ServiceUrl));
            var response = await connectorClient.Conversations.CreateConversationAsync(conversationParameters);

            context.Done<object>(null);
        }
    }
}