Mensajería proactiva para bots

Importante

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

Un mensaje proactivo es un mensaje que envía un bot para iniciar una conversación. Es posible que quiera que el bot inicie una conversación por muchas razones, entre las que se incluyen:

• Mensajes de bienvenida para conversaciones de bots personales.
• Sondear las respuestas.
• Notificaciones de eventos externos.

Enviar un mensaje para iniciar un nuevo subproceso de conversación es diferente de enviar 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 qué va a decir
2. Obtener el identificador único del usuario y el identificador de inquilino
3. Enviar el mensaje

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

Procedimientos recomendados para la mensajería proactiva

El envío de mensajes proactivos a los usuarios es una manera eficaz de comunicarse con los usuarios. Sin embargo, desde la perspectiva del usuario, el mensaje aparece sin aprobaciones. Si hay un mensaje de bienvenida, es la primera vez que interactúan 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 aparece sin ser solicitado. Si hay un mensaje de bienvenida, es la primera vez que interactúan con la aplicación. Los mejores mensajes de bienvenida incluyen:

• Por qué reciben este mensaje: debería estar claro para el usuario por qué recibe este mensaje. Si el bot se instaló en un canal y envió un mensaje de bienvenida a todos los usuarios, hágales saber en qué canal se instaló y quién lo instaló.
• Qué ofrece: qué pueden hacer con la aplicación. ¿Qué valor puede aportarles?
• Qué deben hacer a continuación: invitar a los usuarios a probar un comando o interactuar con la aplicación.

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 basadas en la notificación y comprender claramente por qué se produjo la notificación. Por lo general, los mensajes de notificación correctos incluyen:

• Qué ha ocurrido: una indicación clara de lo que ha ocurrido para recibir la notificación.
• Qué pasó con: debe estar claro qué elemento u objeto se actualizó para provocar la notificación.
• Quién o qué la activó: quién o qué realizó la acción que provocó el envío de la notificación.
• Qué pueden hacer los usuarios en respuesta: facilite a los usuarios la realización de acciones basadas en sus notificaciones.
• Cómo pueden optar por no participar: proporcione una ruta de acceso para que los usuarios no puedan participar en notificaciones adicionales.

Obtención de la información de usuario necesaria

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

• Al capturar la lista de equipos de un canal que está instalada la aplicación.
• Al almacenarlos en caché cuando un usuario interactúa con el bot en un canal.
• Cuando un usuario se @mentioned en una conversación de canal del que el bot forma parte.
• Al almacenarlos en caché al recibir el evento conversationUpdate cuando la aplicación está instalada en un ámbito personal, o se agregan nuevos miembros a un canal o chat de grupo.

Instale proactivamente su aplicación con Graph

Nota:

La instalación proactiva de aplicaciones mediante graph está en versión beta.

En ocasiones, es posible que sea necesario enviar mensajes de forma proactiva a los usuarios que no hayan instalado o interactuado con la aplicación anteriormente. Por ejemplo, desea usar el comunicador de la empresa para enviar mensajes a toda la organización. En este escenario, puede 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 conversationUpdate que recibirá la aplicación tras la instalación.

Solo puede instalar aplicaciones que se encuentran en el catálogo de aplicaciones de la organización o en la Tienda Microsoft Teams.

Consulte Instalación de aplicaciones para usuarios en la documentación de Graph para obtener detalles completos. 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 mediante la 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"
    }
  }
}

Proporcione id como identificador de la aplicación de bot y name como nombre del bot. Puede obtener el membersid objeto de los bots TurnContext , como turnContext.Activity.From.Id. Del mismo modo, id del inquilino, desde el objeto bots TurnContext , como turnContext.Activity.ChannelData.Tenant.Id.

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. Almacenar este valor y reutilizarlo para futuras interacciones con el usuario.

Uso de .NET

En este ejemplo se usa el paquete Microsoft.Bot.Connector.Teams de NuGet.

// 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 de Teams, use startReplyChain(), que proporciona una dirección completamente rellenada con el identificador de actividad y el identificador de conversación correctos. Si usa C#, consulte el ejemplo siguiente.

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

Ejemplos para crear una conversación de canal

C#

El ejemplo de .NET 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);
        }
    }
}

Node.js

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

HTTP

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

Puede obtener el {Service URL of your bot} objeto from TurnContext como turnContext.Activity.ServiceURL parámetro.

Puede obtener el channelData objeto from TurnContext como turnContext.Activity.TeamsChannelData parámetro.

Proporcione id como identificador de la aplicación de bot y name como nombre del bot. Del mismo modo, id del inquilino, desde el objeto bots TurnContext , como turnContext.Activity.ChannelData.Tenant.Id.

Del mismo modo, puede proporcionar para teamIDteamsChannelId, teamsTeamId, channel, team en channelData la sección , que envía el mensaje al canal general del equipo.

Si la llamada se realiza correctamente, la API devuelve con el siguiente objeto de respuesta:

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

Consulte también

Ejemplos de Bot Framework.