Mensajería proactiva para bots

Importante

Este artículo se basa en el SDK de Bot Framework de v3. Si está buscando la documentación actual versión 4.6 o posterior del SDK, consulte la sección bots de conversación.

Un mensaje proactivo es un mensaje que envía un bot para iniciar una conversación. Puede que quiera que el bot inicie una conversación por varios motivos, entre los que se incluyen:

  • Mensajes de bienvenida para conversaciones de bot personales
  • Respuestas de sondeo
  • Notificaciones de eventos externos

El envío de un mensaje para iniciar un nuevo hilo de conversación es diferente al envío de un mensaje en respuesta a una conversación existente: cuando el bot inicia una nueva conversación, no hay ninguna conversación existente en la que publicar el mensaje. Para enviar un mensaje proactivo, debe:

  1. Decidir lo que vas a decir
  2. Obtener el identificador único del usuario y el identificador de inquilino
  3. Enviar el mensaje

Al crear mensajes proactivos, debe llamar y pasar la dirección URL del servicio antes de crear la usada para enviar MicrosoftAppCredentials.TrustServiceUrl el ConnectorClient mensaje. Si no lo hace, la aplicación recibe una 401: Unauthorized respuesta. Para obtener más información, vea los ejemplos siguientes.

Procedimientos recomendados para mensajería proactiva

Enviar mensajes proactivos es una forma eficaz de comunicarse con los usuarios. Sin embargo, desde la perspectiva del usuario, el mensaje no aparece. Si hay un mensaje de bienvenida, será la primera vez que interactúen con la aplicación. Es importante usar esta funcionalidad y proporcionar la información completa al usuario para comprender el propósito de este mensaje.

Generalmente, los mensajes proactivos se divide en dos categorías: mensajes de bienvenida o notificaciones.

Mensajes de bienvenida

Al usar la mensajería proactiva para enviar un mensaje de bienvenida a un usuario, asegúrese de que, desde la perspectiva del usuario, el mensaje no aparece. Si hay un mensaje de bienvenida, será la primera vez que interactúen con la aplicación. Los mejores mensajes de bienvenida incluirán:

  • Por qué están recibiendo este mensaje: debe ser claro para el usuario por qué están recibiendo este mensaje. Si el bot se instaló en un canal y envió un mensaje de bienvenida a todos los usuarios, hágles saber en qué canal se instaló y quién lo instaló.
  • **Qué ofreces:**¿Qué pueden hacer con la aplicación? ¿Qué valor puede aportarles?
  • Qué deben hacer a continuación: Invítelos a probar un comando o interactuar con la aplicación de alguna manera.

Mensajes de notificación

Al usar la mensajería proactiva para enviar notificaciones, debe asegurarse de que los usuarios tienen una ruta de acceso clara para realizar acciones comunes en función de la notificación y una comprensión clara de por qué se produjo la notificación. Por lo general, los mensajes de notificación de buena calidad incluirán:

  • What happened: A clear indication of what happened to cause the notification.
  • Qué sucedió con: Debe estar claro qué elemento/cosa se actualizó para provocar la notificación.
  • Quién: ¿Quién realizó la acción que hizo que se enviara la notificación?
  • Qué pueden hacer al respecto: facilita a los usuarios realizar acciones en función de las notificaciones.
  • Cómo pueden optar por no participar: proporcionar una ruta de acceso para que los usuarios no puedan participar en notificaciones adicionales.

Obtener información de usuario necesaria

Los bots pueden crear nuevas conversaciones con un usuario Microsoft Teams individual obteniendo el identificador único del usuario y el identificador de inquilino. Puede obtener estos valores mediante uno de los siguientes métodos:

Instale proactivamente la aplicación con Graph

Nota

La instalación proactiva de aplicaciones con graph se encuentra actualmente en fase beta.

En ocasiones, es posible que sea necesario enviar mensajes de forma proactiva a los usuarios que no han instalado o interactuado con la aplicación anteriormente. Por ejemplo, desea usar el comunicador de la compañía para enviar mensajes a toda la organización. Para este escenario, puedes usar la API de Graph para instalar proactivamente la aplicación para los usuarios y, a continuación, almacenar en caché los valores necesarios del evento que la aplicación recibirá al conversationUpdate instalarla.

Solo puedes instalar aplicaciones que estén en el catálogo de aplicaciones de la organización o en la Teams de aplicaciones.

Consulta Instalar aplicaciones para usuarios en la Graph documentación para obtener información completa. También hay un ejemplo en .NET.

Ejemplos

Asegúrese de autenticarse y tener un token de portador antes de crear una nueva conversación con la API de REST.

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

Debe proporcionar el identificador de usuario y el identificador de inquilino. Si la llamada se realiza correctamente, la API devuelve el siguiente objeto de respuesta.

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

Este identificador es el identificador de conversación único del chat personal. Almacene este valor y reutilice para futuras interacciones con el usuario.

Uso de .NET

En este ejemplo se usa microsoft.bot.connector.Teams NuGet paquete.

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

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

Crear una conversación de canal

El bot agregado por el equipo puede publicar en un canal para crear una nueva cadena de respuesta. Si usa el SDK de Node.js Teams, use , que le proporciona una dirección completa con el identificador de actividad y el identificador de startReplyChain() conversación correctos. Si usas C#, consulta el ejemplo siguiente.

Como alternativa, puede usar la API de REST y emitir una solicitud POST al /conversations recurso.

Ejemplo de .NET (de este ejemplo)

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

Vea también

Ejemplos de Bot Framework