Mensajes proactivos

  • Artículo

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 busca documentación para versiones anteriores, consulte la sección bots - v3 SDK en la carpeta SDK heredados de la documentación.

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

  • Mensajes de bienvenida
  • Notificaciones
  • Mensajes programados

Importante

Para enviar un mensaje proactivo a un usuario, un chat de grupo o un equipo, el bot debe tener el acceso necesario para enviar el mensaje. La aplicación que contiene el bot debe instalarse en primer lugar en un chat de grupo o de equipo.

Puede instalar proactivamente la aplicación mediante Microsoft Graph en un equipo, si es necesario, o usar una directiva de aplicación personalizada para instalar una aplicación en los equipos y para los usuarios de la organización. Para determinados escenarios, debe instalar de forma proactiva la aplicación mediante Graph. Para que un usuario reciba mensajes proactivos, instale la aplicación para el usuario o convierta al usuario en parte de un equipo en el que está instalada la aplicación.

Enviar un mensaje proactivo es diferente a enviar un mensaje normal. No hay ningún activo turnContext que usar como respuesta. Debe crear la conversación antes de enviar el mensaje. Por ejemplo, un nuevo chat uno a uno o un nuevo subproceso de conversación en un canal. No puede crear un nuevo chat grupal ni un canal nuevo en un equipo con mensajería proactiva.

Para enviar un mensaje proactivo, siga estos pasos:

  1. Obtenga el Microsoft Entra id. de usuario, id. de usuario, id. de equipo o id. de canal, si es necesario.
  2. Cree la conversación, si es necesario.
  3. Obtenga el identificador de conversación.
  4. Envíe el mensaje.

Los fragmentos de código de la sección de ejemplos son para crear una conversación uno a uno. Para ver vínculos a ejemplos de conversaciones uno a uno y mensajes de grupo o canales, consulte ejemplo de código. Para usar mensajes proactivos de forma eficaz, consulte los procedimientos recomendados para la mensajería proactiva.

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

Puede crear una nueva conversación con un usuario o un subproceso de conversación en un canal y debe tener el identificador correcto. Puede recibir o recuperar este identificador mediante cualquiera de las siguientes maneras:

  • Cuando la aplicación se instala en un contexto determinado, recibe una onMembersAdded actividad.
  • Cuando se agrega un nuevo usuario a un contexto donde está instalada la aplicación, recibe una onMembersAdded actividad.
  • Cada evento que recibe el bot contiene la información necesaria, que puede obtener del contexto del bot (objeto TurnContext).
  • Puede recuperar la lista de canales en un equipo donde está instalada la aplicación.
  • Puede recuperar la lista de miembros de un equipo donde está instalada la aplicación.

Independientemente de cómo obtenga la información, almacene tenantId y, a continuación, almacene , userIdo channelId para crear una nueva conversación. También puede usar el teamId para crear un nuevo hilo de conversación en el canal general o predeterminado de un equipo. Asegúrese de que el bot está instalado en el equipo antes de poder enviar un mensaje proactivo a un canal.

  • es aadObjectId único para el usuario y se puede recuperar mediante graph API para crear una nueva conversación en el chat personal. Asegúrese de que el bot está instalado en el ámbito personal antes de poder enviar un mensaje proactivo. Si el bot no está instalado en un ámbito personal al enviar un mensaje proactivo mediante aadObjectId, el bot devuelve un error con ForbiddenOperationException el 403 mensaje .

  • El userId es único para el identificador del bot y un usuario en particular. No se puede volver a usar el userId entre bots.

  • El channelId es global.

Create la conversación, después de tener la información del usuario o del canal.

Nota:

El envío de mensajes proactivos mediante aadObjectId solo se admite en el ámbito personal.

Crear la conversación

Puede crear la conversación si no existe o no conoce .conversationId Create la conversación una sola vez y almacene el conversationId valor o conversationReference el objeto.

Para crear la conversación, necesita o aadObjectIduserId, tenantIdy serviceUrl.

Para serviceUrl, use el valor de una actividad entrante que desencadena el flujo o una de las direcciones URL de servicio globales. serviceUrl Si no está disponible en una actividad entrante que desencadena el escenario proactivo, use los siguientes puntos de conexión de dirección URL globales:

  • Público: https://smba.trafficmanager.net/teams/
  • GCC: https://smba.infra.gcc.teams.microsoft.com/teams
  • GCCH: https://smba.infra.gov.teams.microsoft.us/teams
  • DOD: https://smba.infra.dod.teams.microsoft.us/teams

Para obtener un ejemplo de código, vea la llamada CreateConversationAsync en el ejemplo.

Puede obtener la conversación cuando la aplicación se instala por primera vez. Una vez creada la conversación, obtenga el identificador de conversación. conversationId está disponible en los eventos de actualización de conversación.

El identificador de conversación es único para cada bot dentro de un canal específico, incluso en un entorno multiinquilino. Este identificador garantiza que los mensajes del bot se dirijan al canal adecuado y no interrumpan con otros bots o canales dentro de la misma organización o entre distintas organizaciones.

Si no tiene conversationId, puede instalar la aplicación de forma proactiva mediante Graph para obtener conversationId.

Obtener el identificador de conversación

Use el conversationReference objeto o conversationId y tenantId para enviar el mensaje. Puede obtener este identificador creando la conversación o almacenándola 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 continueConversation y el conversationId y tenantId para realizar una llamada API directa. Para enviar el mensaje, establezca .conversationParameters Vea la sección de ejemplos o use uno de los ejemplos mostrados en la sección de ejemplo de código.

Nota:

Teams no admite el envío de mensajes proactivos mediante correo electrónico o nombre principal de usuario (UPN).

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

Vea el siguiente vídeo para aprender a enviar mensajes proactivos desde bots:



Descripción de quién ha bloqueado, silenciado o desinstalado un bot

Como desarrollador, puede crear un informe para comprender qué usuarios de su organización han bloqueado, silenciado o desinstalado un bot. Esta información puede ayudar a los administradores de la organización a difundir mensajes en toda la organización o a impulsar el uso de la aplicación.

Con Teams, puede enviar un mensaje proactivo al bot para comprobar si un usuario ha bloqueado o desinstalado un bot. Si el bot está bloqueado o desinstalado, Teams devuelve un 403 código de respuesta con .subCode: MessageWritesBlocked Esta respuesta indica que el mensaje enviado por el bot no se entrega al usuario.

El código de respuesta se envía por usuario e incluye la identidad del usuario. Puede compilar los códigos de respuesta de cada usuario junto con su identidad para crear un informe de todos los usuarios que han bloqueado el bot.

A continuación se muestra un ejemplo de código de respuesta 403.


HTTP/1.1 403 Forbidden

Cache-Control: no-store, must-revalidate, no-cache

 Pragma: no-cache

 Content-Length: 196

 Content-Type: application/json; charset=utf-8

 Server: Microsoft-HTTPAPI/2.0

 Strict-Transport-Security: max-age=31536000; includeSubDomains

 MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0

 ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0

 Date: Tue, 29 Mar 2022 17:34:33 GMT

{"errorCode":209,"message":"{\r\n  \"subCode\": \"MessageWritesBlocked\",\r\n  \"details\": \"Thread is blocked from message writes.\",\r\n  \"errorCode\": null,\r\n  \"errorSubCode\": null\r\n}"}

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, 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 por qué el usuario recibe el mensaje. Además, esta es la primera interacción del usuario con la aplicación. Es una oportunidad para crear una buena primera impresión. Una buena experiencia de usuario garantiza una mejor adopción de la aplicación. Los mensajes de bienvenida deficientes pueden llevar a los usuarios a bloquear la aplicación. Escriba un mensaje de bienvenida claro e itere en el mensaje de bienvenida si no tiene el efecto deseado.

Un buen mensaje de bienvenida puede incluir lo siguiente:

  • Motivo del mensaje: debe estar claro para el usuario por qué recibe el mensaje. Si su 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ó.

  • Su oferta: los usuarios deben poder identificar lo que pueden hacer con la aplicación y qué valor puede aportarles.

  • Pasos siguientes: los usuarios deben comprender los pasos siguientes. Por ejemplo, invite a los usuarios a probar un comando o a interactuar con la aplicación.

Mensajes de notificación

Para enviar notificaciones mediante mensajería proactiva, asegúrese de que los usuarios tienen una ruta clara para realizar acciones comunes basadas en la notificación. Si se requieren acciones de usuario en una aplicación de pestaña, use notificaciones de fuente de actividad en lugar de un bot. Asegúrese de que los usuarios comprendan claramente por qué han recibido una notificación. Por lo general, los mensajes de notificación correctos incluyen los siguientes elementos:

  • ¿Qué ha ocurrido? Una indicación clara de lo que ha ocurrido para recibir la notificación.

  • ¿Cuál fue el resultado? Debe quedar claro, qué elemento se actualiza para obtener la notificación.

  • ¿Quién o qué lo desencadenó? Quién o qué tomó medidas, lo que hizo que se enviara 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 los usuarios por no participar? Debe proporcionar una ruta de acceso para que los usuarios opten por no recibir más notificaciones.

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

Mensajes programados

Cuando utilice la mensajería proactiva para enviar mensajes programados a los usuarios, verifique que su zona horaria esté actualizada a su zona horaria. Esto garantiza que los mensajes se entreguen a los usuarios en el momento pertinente. Por lo general, los mensajes de programación incluyen:

  • ¿Por qué el usuario recibe el mensaje? Facilite a sus usuarios la razón por la que están recibiendo el mensaje.

  • ¿Qué puede hacer el usuario ahora? Los usuarios pueden realizar la acción requerida en base al contenido del mensaje.

Instale proactivamente su aplicación con Graph

Envíe mensajes proactivos a los usuarios que no hayan instalado o interactuado con su aplicación. Por ejemplo, desea usar el comunicador de la empresa para enviar mensajes a toda la organización. En este caso, puede usar la API de Graph para instalar de forma proactiva la aplicación para los usuarios. Almacene en caché los valores necesarios del conversationUpdate evento que recibe su 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 instalar aplicaciones para usuarios en la documentación de Graph e instalación proactiva de bots y mensajería en Teams con Graph. También hay un ejemplo de Microsoft .NET Framework en la plataforma GitHub.

Ejemplos

Asegúrese de autenticarse y de tener un token de portador antes de crear una nueva conversación mediante la API REST. A continuación se muestra la API REST para crear una conversación en contextos diferentes:

  • API REST para crear una conversación en un chat uno a uno.

  • API REST para crear una conversación en un canal.

  • API REST para actualizar el mensaje en la conversación: para actualizar una actividad existente dentro de una conversación, incluya conversationId y activityId en el punto de conexión de solicitud. Para completar este escenario, debe almacenar en caché el identificador de actividad devuelto por la llamada post original.

    PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}

    
{
    "type": "message",
    "text": "This message has been updated"
}

    Para actualizar una actividad existente en una conversación, incluya el conversationId y activityId en el punto de conexión de solicitud. Para completar este escenario, debe almacenar en caché el activity ID devuelto por la llamada posterior original. Si la llamada se realiza correctamente, la API devuelve el siguiente objeto de respuesta:

    {
    "id": "{{activityID}}"
}

Muestras

El código siguiente 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)
        {
            var newReference = new ConversationReference()
            {
                Bot = new ChannelAccount()
                {
                    Id = conversationReference.Bot.Id
                },
                Conversation = new ConversationAccount()
                {
                    Id = conversationReference.Conversation.Id
                },
                ServiceUrl = conversationReference.ServiceUrl,
            };

            // Sends a proactive message from the bot to a conversation.
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, newReference, 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://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp#avoiding-401-unauthorized-errors
        // Sends an activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Ejemplo de un fragmento de código para mostrar la creación de una referencia de conversación.

 var newReference = new ConversationReference()
        {
            Bot = new ChannelAccount()
            {
                Id = conversationReference.Bot.Id
            },
            Conversation = new ConversationAccount()
            {
                Id = conversationReference.Conversation.Id
            },
            ServiceUrl = conversationReference.ServiceUrl,
        };

Ejemplo de código

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

Nombre de ejemplo Descripción .NET Node.js Python Manifiesto
Conceptos básicos de conversación de Teams Esta aplicación de ejemplo muestra cómo usar diferentes eventos de conversación de bot disponibles en bot framework v4 para el ámbito personal y de teams. View View View View
Iniciar nuevo hilo en un canal En este ejemplo se muestra cómo iniciar un subproceso en el canal de un equipo específico mediante Bot Framework v4. View View View View
Instalación proactiva de la aplicación y envío de notificaciones proactivas En este ejemplo se muestra cómo puede usar la instalación proactiva de la aplicación para usuarios y enviar notificaciones proactivas mediante una llamada a las API de Microsoft Graph. View View ND View
Mensajería proactiva Este es un ejemplo que muestra cómo guardar la información de referencia de conversación del usuario para enviar un mensaje de recordatorio proactivo mediante bots. View View ND

Más ejemplo de código de mensajería proactiva

Paso siguiente

Formatear los mensajes del bot

Vea también