Mensajería proactiva para bots

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 muchas razones, entre las que se incluyen:

• Mensajes de bienvenida para conversaciones de bots personales.
• Respuestas a sondeos.
• Notificaciones de eventos externos.

Enviar un mensaje para iniciar una nueva conversación no es lo mismo que enviar un mensaje en respuesta a una conversación existente. Cuando el bot inicia una nueva conversación, no hay ninguna conversación preexistente en la que publicar el mensaje. Para enviar un mensaje proactivo, debe:

1. Decide 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 a MicrosoftAppCredentials.TrustServiceUrly pasar la dirección URL del servicio antes de crear la ConnectorClient utilizada para enviar el mensaje. Si no lo hace, su aplicación recibirá una 401: Unauthorized respuesta. Para obtener más información, consulte los ejemplos.

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 aparece sin solicitar. 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 que comprenda el propósito de este mensaje.

Los mensajes proactivos generalmente se dividen en una de dos categorías: mensajes de bienvenida o notificaciones.

Mensajes de bienvenida

Cuando use mensajes proactivos para enviar un mensaje de bienvenida a un usuario, asegúrese de que, desde la perspectiva del usuario, el mensaje aparezca sin solicitar. 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é recibe este mensaje: debe quedar 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, potencialmente, quién lo instaló.
• Qué ofreces: ¿Qué pueden hacer con tu aplicación? ¿Qué valor puede aportarles?
• Qué deben hacer a continuación: Invítelos a probar un comando o interactuar con su aplicación de alguna manera.

Mensajes de notificación

Al usar la mensajería proactiva para enviar notificaciones, debe asegurarse de que los usuarios tengan una ruta clara para realizar acciones comunes basadas en la notificación y una comprensión clara de por qué se produjo la notificación. Los mensajes de notificación válidos generalmente incluyen:

• Qué ha ocurrido: Una indicación clara de lo que ha ocurrido para provocar la notificación.
• Qué sucedió con: Debe quedar claro qué elemento / cosa se actualizó para causar la notificación.
• Quién lo hizo: ¿quién tomó la acción que provocó que se enviara la notificación?
• Qué pueden hacer al respecto: facilite a sus usuarios tomar medidas basadas en sus notificaciones.
• Cómo pueden optar por no participar: proporcione una ruta para que los usuarios opten por no recibir notificaciones adicionales.

Obtener la información de usuario necesaria

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

• Al capturar la lista de equipo de un canal, se instala la aplicación.
• Almacenándolos en caché cuando un usuario interactúa con el bot en un canal.
• Cuando se @mentioned un usuario en una conversación de canal de la que forma parte el bot.
• Almacenándolos en caché cuando reciba el evento, cuando se instale la conversationUpdate aplicación en un ámbito personal o se agreguen nuevos miembros a un canal o chat grupal que.

Instalación proactiva de la aplicación con Graph

En ocasiones, puede que sea necesario enviar mensajes proactivamente a los usuarios que no han instalado o no han interactuado con su aplicación anteriormente. Por ejemplo, quiere usar el comunicador de la empresa para enviar mensajes a toda la organización. En este escenario, puede usar la Graph API para instalar proactivamente la aplicación para los usuarios y, a continuación, almacenar en caché los valores necesarios del evento que recibirá la aplicación durante la conversationUpdate instalación.

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

Consulte Instalación de aplicaciones para usuarios en la documentación de Graph para obtener información completa. También hay un ejemplo en .NET.

Ejemplos

Asegúrese de autenticarse y de disponer de 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"
    }
  }
}

Indíquelo id como id. de la aplicación bot y name como nombre del bot. Puede obtener el membersid objeto de sus bots TurnContext , como turnContext.Activity.From.Id. Del mismo modo, id de inquilino, de sus objetos de 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. Almacene este valor y vuelva a usarlo para futuras interacciones con el usuario.

Uso de .NET

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

Usar 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 respuestas. Si usa el SDK de Node.js Teams, use startReplyChain(), que le proporciona 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 utilizar la API REST y emitir una solicitud POST al /conversations recurso.

Ejemplos para crear una conversación 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
)

Vea también

Ejemplos de Bot Framework.