Mensagens proativas para bots

Artigo
05/25/2024

Importante

Este artigo baseia-se no SDK v3 do Bot Framework. Se estiver à procura da versão atual da documentação 4.6 ou posterior do SDK, consulte a secção bots de conversação .

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 conversações pessoais do bot.
Respostas às sondagens.
Notificações de eventos externos.

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

Decidir o que você vai dizer
Obter a ID exclusiva do usuário e a ID do locatário
Enviar a mensagem

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

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, é a primeira vez que interagem com a sua aplicação. É importante usar essa funcionalidade e fornecer as informações completas ao usuário para entender a finalidade dessa mensagem.

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

Mensagem 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 parece não ser proativa. Se existir uma mensagem de boas-vindas, é a primeira vez que interagem com a sua aplicação. As melhores mensagens de boas-vindas incluem:

por quê eles estão recebendo esta mensagem: deve ser claro para o usuário por quê 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, deixe-os saber em qual canal ele foi instalado e quem o instalou.
o que você oferece: o que eles podem fazer com seu aplicativo? Qual valor você pode trazer para eles?
o que eles devem fazer em seguida: convidar os usuários para tentar um comando ou interagir com seu aplicativo.

Mensagens de notificação

Ao utilizar mensagens proativas para enviar notificações, tem de se certificar de que os seus utilizadores têm um caminho claro para efetuar ações comuns com base na sua notificação e uma compreensão clara do motivo pelo qual a notificação ocorreu. Geralmente, as boas mensagens de notificação incluem:

o que aconteceu: uma indicação clara do que aconteceu para gerar a notificação.
Com o que aconteceu: deve estar claro qual item/coisa foi atualizado para causar a notificação.
quem fez isso: quem executou a ação que fez com que a notificação seja enviada?
O que eles podem fazer a respeito: torne fácil para os usuários tomarem 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 conversações com um utilizador individual do Microsoft Teams ao obter o ID exclusivo do utilizador e o ID de inquilino. Pode obter estes valores com um dos seguintes métodos:

Ao buscar a lista de participantes de um canal em que seu aplicativo está instalado.
Armazenando-os em cache quando um usuário interage com seu bot em um canal.
Quando um usuário é @mencionado em uma conversa de canal da qual o bot faz parte.
Armazenando-os em cache quando você recebe oconversationUpdate evento quando seu aplicativo é instalado em um escopo pessoal ou novos membros são adicionados a um canal ou chat em grupo que.

Instalar proativamente seu aplicativo usando o Graph

Observação

A instalação proativa de aplicações com grafos está em versão beta.

Ocasionalmente, pode ser necessário enviar mensagens proativas 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 o API do Graph para instalar proativamente seu aplicativo para seus usuários e, em seguida, armazenar em cache os valores necessários do evento conversationUpdate que seu aplicativo receberá após a instalação.

Só pode instalar aplicações que estejam no seu catálogo de aplicações organizacionais ou na Microsoft Teams Store.

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

Exemplos

Certifique-se de que autentica e tem um token de portador antes de criar uma nova conversação com 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"
    }
  }
}

Indique id como o ID da aplicação do bot e name como o nome do bot. Pode obter o do membersid objeto bots TurnContext , como turnContext.Activity.From.Id. Da mesma forma, id do inquilino, do objeto bots TurnContext , como turnContext.Activity.ChannelData.Tenant.Id.

É 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"

}

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

Criar uma conversa de canal

Seu bot adicionado pela equipe pode postar em um canal para criar uma nova cadeia de respostas. Se você estiver usando o SDK do Teams do Node.js, usestartReplyChain(), que fornece um endereço totalmente preenchido com a ID de atividade e a ID de conversa corretas. Se estiver a utilizar C#, veja o seguinte exemplo.

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

Exemplos para criar uma conversação de canal

O exemplo de .NET é deste exemplo

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}}"
}

Pode obter o {Service URL of your bot} do TurnContext objeto como turnContext.Activity.ServiceURL o parâmetro .

Pode obter o channelData do TurnContext objeto como turnContext.Activity.TeamsChannelData o parâmetro .

Indique id como o ID da aplicação do bot e name como o nome do bot. Da mesma forma, id do inquilino, do objeto bots TurnContext , como turnContext.Activity.ChannelData.Tenant.Id.

Da mesma forma, pode fornecer o teamID para teamsChannelId, teamsTeamId, channel, team na channelData secção, que envia a mensagem para o canal geral da equipa.

Se a chamada for bem-sucedida, a API devolve com o seguinte objeto de resposta:

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

Confira também

Amostras do Bot Framework.

Compartilhar via