Enviar mensajes proactivos

Nota

En los ejemplos de código de este artículo se usa el SDK de V3 Framework SDK y las extensiones de SDK de Teams bot Builder de V3. Conceptualmente, la información se aplica cuando se usan las versiones V4 del SDK, pero el código es ligeramente diferente.

Un mensaje proactivo es un mensaje enviado por un bot para iniciar una conversación. Es posible que desee que el bot inicie una conversación por varios motivos, entre los que se incluyen:

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

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

  1. Decide qué vas a decir
  2. Obtener el identificador único del usuario y el identificador de inquilino
  3. Enviar el mensaje

Al crear mensajes proactivos must a los MicrosoftAppCredentials.TrustServiceUrlque se debe llamar y pasar la dirección URL del ConnectorClient servicio antes de crear el, se usará para enviar el mensaje. Si no lo hace, la aplicación recibirá una 401: Unauthorized respuesta.

Procedimientos recomendados para la mensajería proactiva

El envío de mensajes proactivos a los usuarios puede ser una forma muy eficaz de comunicarse con los usuarios. Sin embargo, desde su perspectiva puede parecer que este mensaje no se solicita completamente y, en el caso de los mensajes de bienvenida, será la primera vez que interactuen con la aplicación. Por lo tanto, es muy importante usar esta funcionalidad con moderación (no enviar correo no deseado a los usuarios) y proporcionarle la información suficiente para que puedan comprender por qué se les está enviando un mensaje.

Generalmente, los mensajes proactivos se dividen 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, debe tener en cuenta que para la mayoría de las personas que reciben el mensaje no tendrán contexto por el motivo por el que lo reciben. También es la primera vez que interactuarán con la aplicación; es su oportunidad para crear una buena primera impresión. Los mejores mensajes de bienvenida incluirán:

  • ¿Por qué reciben este mensaje? El usuario debe ser muy claro por qué reciben el mensaje. Si el bot se ha instalado en un canal y se ha enviado un mensaje de bienvenida a todos los usuarios, hágales saber en qué canal se ha instalado y que podrían instalarlo.
  • Qué ofrece. ¿Qué puede hacer con la aplicación? ¿Qué valor puede aportar a ellos?
  • Qué debería hacer a continuación. Invitar 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 emprender acciones comunes en función de la notificación y un conocimiento claro de la razón por la que se produjo la notificación. Por lo general, los mensajes de notificación son correctos:

  • Qué ha pasado. Una indicación clara de lo que ha sucedido para provocar la notificación.
  • Qué ocurrió. Debe estar claro qué elemento/Thing se actualizó para provocar la notificación.
  • Quién lo llevó a cabo. Quién llevó a cabo la acción que hizo que se enviara la notificación.
  • Qué pueden hacer al respecto. Facilite a los usuarios que realicen acciones basadas en las notificaciones.
  • Cómo se pueden dejar de participar. Debe proporcionar una ruta de acceso para que los usuarios puedan optar por las notificaciones adicionales.

Obtener información de usuario necesaria

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

Instalar de forma proactiva la aplicación con Graph

Nota

La instalación de aplicaciones de forma proactiva con Graph se encuentra actualmente en versión beta.

En ocasiones, es posible que sea necesario enviar un mensaje de forma proactiva a los usuarios que no hayan instalado ni interactúen con la aplicación anteriormente. Por ejemplo, desea usar el Communicator de la compañía para enviar mensajes a toda la organización. Para este escenario, puede usar la API de Graph para instalar proactivamente la aplicación para sus usuarios y, a continuación, almacenar en conversationUpdate caché los valores necesarios del evento que la aplicación recibirá en el momento de la instalación.

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

Consulte install apps for users en la documentación de Graph para obtener detalles completos. También hay un ejemplo en .net.

Ejemplos

Asegúrese de autenticar y de tener un token de portador antes de crear una nueva conversación mediante la API de REST. El members.id campo del siguiente objeto es único para la combinación de Bot y un usuario. No puede obtenerla a través de cualquier otro método que no se haya descrito anteriormente.

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 de chat personal. Almacene este valor y vuelva a usarlo para interacciones futuras con el usuario.

En este ejemplo se usa el paquete 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);

Crear una conversación de canal

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

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

El siguiente fragmento de código es 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);
        }
    }
}