Mensajes proactivos

Importante

Los ejemplos de código de esta sección se basan en la versión 4.6 y versiones posteriores del SDK de Bot Framework. Si está buscando documentación para versiones anteriores, consulte la sección bots - v3 SDK en la carpeta Resources de la documentación.

Un mensaje proactivo es cualquier mensaje enviado por un bot que no responde a una solicitud de un usuario. Esto puede incluir mensajes, como:

  • Mensajes de bienvenida
  • Notificaciones
  • Mensajes programados

Para que el bot envíe un mensaje proactivo a un usuario, chat de grupo o equipo, debe tener acceso para enviar el mensaje. Para un chat de grupo o un equipo, la aplicación que contiene el bot debe instalarse primero en esa ubicación. Puedes instalar proactivamente la aplicación con Microsoft Graph en un equipo, si es necesario, o usar una directiva de aplicación para enviar aplicaciones a equipos y usuarios de tu inquilino. Para los usuarios, la aplicación debe estar instalada para el usuario o el usuario debe formar parte de un equipo donde esté instalada la aplicación.

Enviar un mensaje proactivo es diferente del envío de un mensaje normal. No hay ningún activo turnContext que usar para una respuesta. Debe crear la conversación antes de enviar el mensaje. Por ejemplo, un nuevo chat uno a uno o un nuevo hilo de conversación en un canal. No puedes crear un nuevo chat de grupo o un nuevo canal en un equipo con mensajería proactiva.

Para enviar un mensaje proactivo

  1. Obtiene el id. de usuario, id. de equipo o id. de canal,si es necesario.
  2. Cree la conversación, si es necesario.
  3. Obtener el identificador de conversación.
  4. Enviar el mensaje.

Los fragmentos de código de la sección samples son para crear una conversación uno a uno. Para ver los vínculos a ejemplos de trabajo completos para conversaciones uno a uno y grupos o canales, vea el ejemplo de código.

Para usar mensajes proactivos de forma eficaz, vea procedimientos recomendados para la mensajería proactiva. Para determinados escenarios, debes instalar proactivamente la aplicación con Graph. Los fragmentos de código de la sección samples son para crear una conversación uno a uno. Para obtener ejemplos de trabajo completos para conversaciones uno a uno y grupos o canales, vea el ejemplo de código.

Obtener el id. de usuario, id. de equipo o id. de canal

Para crear un nuevo hilo de conversación o conversación en un canal, debe tener el identificador correcto. Puede recibir o recuperar este identificador con cualquiera de las siguientes opciones:

  • Cuando la aplicación está instalada en un contexto determinado, recibes una onMembersAdded actividad.
  • Cuando se agrega un nuevo usuario a un contexto donde está instalada la aplicación, recibes una onMembersAdded actividad.
  • Puedes recuperar la lista de canales de un equipo donde está instalada la aplicación.
  • Puedes recuperar la lista de miembros de un equipo donde está instalada la aplicación.
  • Cada actividad que recibe el bot debe contener la información necesaria.

Independientemente de cómo obtenga la información, debe almacenar el o para tenantId userId crear una nueva channelId conversación. También puede usar el para crear un nuevo subproceso de conversación en el canal teamId general o predeterminado de un equipo.

El userId es único para el identificador del bot y un usuario en particular. No puede volver a usar los userId bots entre. El channelId es global. Sin embargo, el bot debe instalarse en el equipo para poder enviar un mensaje proactivo a un canal.

Después de tener la información del usuario o del canal, debe crear la conversación.

Crear la conversación

Debe crear la conversación si no existe o si no conoce el conversationId archivo . Solo debe crear la conversación una vez y almacenar el conversationId valor u conversationReference objeto.

Después de crear la conversación, debe obtener el identificador de conversación.

Obtener el identificador de conversación

Use el conversationReference objeto o y envíe el conversationId tenantId mensaje. Para obtener este identificador, puede crear la conversación o almacenarla desde cualquier actividad que se le envíe desde ese contexto. Almacene este identificador como referencia.

Después de obtener la información de dirección adecuada, puede enviar el mensaje.

Enviar el mensaje

Ahora que tiene la información de dirección correcta, puede enviar el mensaje. Si usa el SDK, debe usar el método y continueConversation y realizar una llamada directa a la conversationId tenantId API. Debe establecer conversationParameters correctamente para enviar correctamente el mensaje. Vea la sección de ejemplos o use uno de los ejemplos enumerados en la sección de ejemplo de código.

Ahora que ha enviado el mensaje proactivo, debe seguir estos procedimientos recomendados mientras envía mensajes proactivos para un mejor intercambio de información entre los usuarios y el bot.

Procedimientos recomendados para mensajería proactiva

Enviar mensajes proactivos a los usuarios 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.

Mensajes de bienvenida

Cuando se usa la mensajería proactiva para enviar un mensaje de bienvenida a un usuario, no hay contexto para la razón por la que los usuarios reciben el mensaje. También es la primera vez que los usuarios interactúan con la aplicación. Es una oportunidad para crear una buena primera impresión. Los mejores mensajes de bienvenida deben incluir:

  • Por qué un usuario recibe el mensaje: debe ser muy claro para el usuario por qué está recibiendo el mensaje. Si el bot se instaló en un canal y envió un mensaje de bienvenida a todos los usuarios, háles saber en qué canal se instaló y quién lo instaló.
  • Qué ofrece: los usuarios deben ser capaces de identificar lo que pueden hacer con la aplicación y qué valor puede aportarles.
  • Qué deben hacer a continuación: Invitar a los usuarios a probar un comando o interactuar con la aplicación. Los mensajes de bienvenida deficientes pueden llevar a los usuarios a bloquear el bot. Escribe en el punto y borra los mensajes de bienvenida. Itera en los mensajes de bienvenida si no tienen el efecto deseado.

Mensajes de notificación

Para enviar notificaciones mediante mensajería proactiva, asegúrese de que los usuarios tienen una ruta de acceso clara para realizar acciones comunes en función de la notificación. Asegúrese de que los usuarios comprendan claramente por qué han recibido una notificación. Por lo general, los mensajes de notificación de buena calidad incluyen lo siguiente:

  • Qué ocurrió: una indicación clara de lo que ocurrió para provocar la notificación.
  • Cuál fue el resultado: debe ser claro, qué elemento se actualiza para obtener la notificación.
  • Quién o lo que lo desencadenó: Quién o lo que hizo que se enviara la notificación.
  • Qué pueden hacer los usuarios en respuesta: facilita que los usuarios realicen acciones en función de las notificaciones.
  • Cómo pueden optar por no participar los usuarios: debe proporcionar una ruta de acceso para que los usuarios no puedan participar en notificaciones adicionales.

Para enviar mensajes a un gran grupo de usuarios, por ejemplo, a su organización, instale proactivamente la aplicación mediante Graph.

Mensajes programados

Al usar la mensajería proactiva para enviar mensajes programados a los usuarios, compruebe que la zona horaria se actualiza a su zona horaria. Esto garantiza que los mensajes se entreguen a los usuarios en el momento correspondiente. Por lo general, los mensajes de programación incluyen:

  • ¿Por qué recibe el usuario el mensaje?: Facilita que los usuarios comprendan el motivo por el que reciben el mensaje.
  • Qué puede hacer el usuario a continuación: los usuarios pueden realizar la acción necesaria en función del contenido del mensaje.

Instale proactivamente la aplicación con Graph

Nota

La instalación proactiva de aplicaciones Graph está actualmente en versión beta.

Envía un mensaje de forma proactiva a los usuarios que no han instalado o interactuado anteriormente con la aplicación. Por ejemplo, desea usar el comunicador de la compañía para enviar mensajes a toda la organización. En este caso, puedes usar la API Graph para instalar proactivamente la aplicación para los usuarios. Almacena en caché los valores necesarios del conversationUpdate evento que la aplicación recibe al instalarlo.

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

Consulta instalar aplicaciones para usuarios en la documentación Graph y la instalación proactiva de botsy la mensajería en Teams con Graph . También hay un ejemplo de Microsoft .NET Framework en la plataforma GitHub.

Muestras

El siguiente código muestra cómo enviar mensajes proactivos:

[Route("api/notify")]
[ApiController]
public class NotifyController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly string _appId;
    private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

    public NotifyController(IBotFrameworkHttpAdapter adapter, IConfiguration configuration, ConcurrentDictionary<string, ConversationReference> conversationReferences)
    {
        _adapter = adapter;
        _conversationReferences = conversationReferences;
        _appId = configuration["MicrosoftAppId"] ?? string.Empty;
    }

    public async Task<IActionResult> Get()
    {
        foreach (var conversationReference in _conversationReferences.Values)
        {
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, conversationReference, BotCallback, default(CancellationToken));
        }
        
        // Let the caller know proactive messages have been sent
        return new ContentResult()
        {
            Content = "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,
        };
    }

    private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
    {
        // If you encounter permission-related errors when sending this message, see
        // https://aka.ms/BotTrustServiceUrl
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Nota

Actualmente, los bots no pueden crear un chat de grupo a través de API de bots o Graph. createConversation solo está disponible para chats 1:1.

Ejemplo de código

En la tabla siguiente se proporciona un ejemplo de código simple que incorpora el flujo de conversación básico en una aplicación de Teams y cómo crear un nuevo subproceso de conversación en un canal en Teams:

Nombre de ejemplo Descripción .NET Node.js Python
Teams Conceptos básicos de conversación Muestra los conceptos básicos de las conversaciones Teams, incluido el envío de mensajes proactivos de uno a uno. View View View
Iniciar nuevo subproceso en un canal Muestra la creación de un nuevo subproceso en un canal. View View View
Instalación proactiva de la aplicación y envío de notificaciones proactivas En este ejemplo se muestra cómo usar la instalación proactiva de la aplicación para los usuarios y enviar notificaciones proactivas llamando a las API Graph Microsoft. View View

Ejemplo de código adicional

Paso siguiente

Consulte también