Sistema de mensagens proativo para bots

Uma mensagem proativa é uma mensagem enviada por um bot para iniciar uma conversa. Talvez você queira que seu bot inicie uma conversa por vários motivos, incluindo:

• Mensagens de boas-vindas para conversas pessoais de bot.
• Respostas de votação.
• Notificações de eventos externos.

Enviar uma mensagem para iniciar uma nova conversa é diferente de enviar uma mensagem em resposta a uma conversa existente. Quando seu bot inicia uma nova conversa, não há nenhuma conversa pré-existente para postar a mensagem. Para enviar uma mensagem proativa, você precisa:

1. Decida o que você vai dizer
2. Obtenha a ID exclusiva do usuário e a ID do locatário
3. Envie a mensagem

Ao criar mensagens proativas, você deve ligar MicrosoftAppCredentials.TrustServiceUrle passar a URL do serviço antes de criar a ConnectorClient usada para enviar a mensagem. Caso contrário, o aplicativo receberá uma 401: Unauthorized resposta. Para obter mais informações, consulte os exemplos.

Práticas recomendadas para mensagens proativas

O envio de mensagens proativas é uma maneira eficaz de se comunicar com os usuários. No entanto, da perspectiva do usuário, a mensagem aparece não solicitada. Se houver uma mensagem de boas-vindas, é a primeira vez que a pessoa interage com seu aplicativo. É importante usar essa funcionalidade e fornecer as informações completas ao usuário para entender o propósito desta mensagem.

As mensagens proativas geralmente se enquadram em uma das duas categorias, mensagens de boas-vindas ou notificações.

Mensagens de boas-vindas

Ao usar mensagens proativas para enviar uma mensagem de boas-vindas a um usuário, verifique se, da perspectiva do usuário, a mensagem aparece não solicitada. Se houver uma mensagem de boas-vindas, é a primeira vez que a pessoa interage com seu aplicativo. As melhores mensagens de boas-vindas incluem:

• Por que eles estão recebendo esta mensagem: deve ficar claro para o usuário por que ele está recebendo esta mensagem. Se o bot foi instalado em um canal e você enviou uma mensagem de boas-vindas a todos os usuários, informe-os em qual canal ele foi instalado e, possivelmente, quem o instalou.
• O que você oferece: o que eles podem fazer com seu aplicativo? Que valor você pode trazer para eles?
• O que eles devem fazer a seguir: convide-os para experimentar um comando ou interagir com seu aplicativo de alguma forma.

Mensagens de notificação

Ao usar mensagens proativas para enviar notificações, você precisa garantir que os usuários tenham um caminho claro para executar ações comuns com base na sua notificação e uma compreensão clara do motivo pela qual a notificação ocorreu. Boas mensagens de notificação geralmente incluem:

• O que aconteceu: uma indicação clara do que aconteceu para causar a notificação.
• Com o que aconteceu: Deve ficar claro qual item/coisa foi atualizado para causar a notificação.
• Quem fez isso: quem tomou a ação que fez com que a notificação fosse enviada?
• O que eles podem fazer: Torne mais fácil para os usuários realizarem ações com base em suas notificações.
• Como eles podem recusar: Forneça um caminho para os usuários recusarem notificações adicionais.

Obter as informações necessárias do usuário

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. Você pode obter esses valores usando um dos seguintes métodos:

• Ao buscar a lista de equipe de um canal, seu aplicativo é instalado.
• Armazenando-os em cache quando um usuário interage com seu bot em um canal.
• Quando um usuário é @mentioned em uma conversa de canal , o bot faz parte.
• Armazenando-os em cache quando você receber o conversationUpdate evento quando seu aplicativo for instalado em um escopo pessoal ou novos membros forem adicionados a um canal ou chat em grupo.

Instale seu aplicativo proativamente usando o Graph

Ocasionalmente, pode ser necessário enviar mensagens proativamente aos usuários que não instalaram ou interagiram com seu aplicativo anteriormente. Por exemplo, você deseja usar o comunicador da empresa para enviar mensagens para toda a organização. 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á após a conversationUpdate instalação.

Você só pode instalar aplicativos que estão em sua organização, catálogo de aplicativos ou na Microsoft Teams Store.

Consulte Instalar aplicativos para usuários na documentação do Graph para obter detalhes completos. Também há um exemplo em .NET.

Exemplos

Certifique-se de autenticar e ter um token de portador antes de criar uma nova conversa usando a API REST.

POST {Service URL of your bot}/v3/conversations

{
  "bot": {
    "id": "c38eda0f-e780-49ae-86f0-afb644203cf8",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

Forneça id a ID do aplicativo de bot e name o nome do bot. Você pode obter o membersid de seus objetos bots TurnContext , como turnContext.Activity.From.Id. Da mesma forma, id do locatário, de seus objetos de bots TurnContext , como turnContext.Activity.ChannelData.Tenant.Id.

Você deve fornecer a ID do usuário e a ID do locatário. Se a chamada for bem-sucedida, a API retornará com o objeto de resposta a seguir.

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

}

Essa ID é a ID de conversa exclusiva do chat pessoal. Armazene esse valor e reutilize-o para interações futuras com o usuário.

Usando o .NET

Este exemplo usa o pacote NuGet Microsoft.Bot.Connector.Teams .

// 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.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);

Criando uma conversa de canal

O bot adicionado à equipe pode postar em um canal para criar uma nova cadeia de respostas. Se você estiver usando o SDK do Node.js Teams, use startReplyChain()o , que fornece um endereço preenchido com a ID de atividade e a ID de conversa corretas. Se você estiver usando C#, no exemplo a seguir.

Como alternativa, você pode usar a API REST e emitir uma solicitação POST para o /conversations recurso.

Exemplos para criar uma conversa de canal

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);
        }
    }
}

export async function startReplyChain(chatConnector: builder.ChatConnector, message: builder.Message, channelId: string): Promise<builder.IChatConnectorAddress> {
    let activity = message.toMessage();

    // Build request
    let options: request.Options = {
        method: "POST",
        // We use urlJoin to concatenate urls. url.resolve should not be used here,
        // since it resolves urls as hrefs are resolved, which could result in losing
        // the last fragment of the serviceUrl
        url: urlJoin((activity.address as any).serviceUrl, "/v3/conversations"),
        body: {
            isGroup: true,
            activity: activity,
            channelData: {
                teamsChannelId: channelId,
            },
        },
        json: true,
    };

    let response = await sendRequestWithAccessToken(chatConnector, options);
    if (response && response.hasOwnProperty("id")) {
        let address = createAddressFromResponse(activity.address, response) as any;
        if (address.user) {
            delete address.user;
        }
        if (address.correlationId) {
            delete address.correlationId;
        }
        return address;
    } else {
        throw new Error("Failed to start reply chain: no conversation ID returned.");
    }
}

POST {Service URL of your bot}/v3/conversations

{
    "activity": {
        "type": "message",
        "text": "new conversation"
    },
    "bot": {
        "id": "{{botID}}",
        "name": "{{botName}}"
    },
    "channelData":{
      "teamsChannelId":"{{teamID}}",
      "teamsTeamId":"{{teamID}}",
      "channel":{"id":"{{teamID}}"},
      "team":{"id":"{{teamID}}"},
      "tenant":{"id": "{{tenantID}}"}
    },
    "isGroup": true,
    "tenantId": "{{tenantID}}"
}

{
    "id": "{{conversationID}}",
    "activityId": "{{activityID}}"
}

from microsoft_teams.apps import App
from microsoft_teams.api import MessageActivityInput
import asyncio

# Bot credentials
app_id = "YOUR_BOT_APP_ID"
app_password = "YOUR_BOT_APP_SECRET"

# Conversation details (obtained from bot installation event)
conversation_id = "19:channelId@thread.tacv2"

# Initialize the Teams app
app = App(
    storage={},
    client_id=app_id,
    client_secret=app_password
)

# Create the message activity
activity = MessageActivityInput(text="Hello from proactive message!")

# Send proactive message using Teams SDK
# The SDK handles authentication, activity construction, and API calls
result = await app.send(
    conversation_id=conversation_id,
    activity=activity
)

Confira também

Exemplos do Bot Framework.