Mensajes proactivos

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

  • Mensajes de bienvenida
  • Notificaciones
  • Mensajes programados

Para enviar un mensaje proactivo a un usuario, un chat grupal o un equipo, el agente debe tener el acceso necesario para enviar el mensaje. Para un chat grupal o un equipo, la aplicación que contiene el agente debe instalarse primero en esa ubicación.

Puede instalar proactivamente la aplicación usando Microsoft Graph en un equipo, si es necesario, o usar una directiva de aplicación personalizada para instalar una aplicación en sus 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 por el usuario o haga que el usuario forme parte de un equipo en el que está instalada la aplicación.

Enviar un mensaje proactivo es diferente a enviar un mensaje normal. Los mensajes proactivos se envían a través de la aplicación. Send() fuera de un controlador de actividades. El SDK crea la conversación automáticamente cuando llamas a la aplicación. Enviar(). Necesita un conversationId, el SDK resuelve la dirección URL del servicio automáticamente. Por ejemplo, un nuevo chat uno a uno o una nueva 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 identificador de usuario, de usuario, de equipo o de canal de Microsoft Entra, 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 obtener vínculos a ejemplos de conversaciones individuales y mensajes de grupo o canales, consulte ejemplos de código. Para usar mensajes proactivos de forma eficaz, consulte los procedimientos recomendados para mensajería proactiva.

Obtener el identificador de usuario, el identificador de usuario, el identificador de equipo o el identificador de canal de Microsoft Entra

Puede crear una nueva conversación con un usuario o una 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 en el que está instalada la aplicación, recibe una onMembersAdded actividad.
  • Cada evento que recibe el agente contiene la información requerida, que puede obtener del contexto del agente (contexto de actividad).
  • 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 ytenantId, a continuación, almacene o channelIduserIdpara crear una 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 agente está instalado en el equipo antes de poder enviar un mensaje proactivo a un canal.

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

  • Es userId único para su ID de agente y un usuario determinado. No se puede volver a userId usar entre agentes.

  • El channelId es global.

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

Nota:

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

Crear la conversación

Puedes crear la conversación si no existe o si no conoces el conversationIdarchivo . Cree la conversación solo una vez y almacene el resultado conversationId para futuros mensajes proactivos.

Para crear la conversación, necesita un aadObjectId or , userIdtenantId, y serviceUrl.

Nota:

Para crear la conversación, pase el aadObjetId valor del Id parámetro.

Para serviceUrl, use el valor de una actividad entrante que desencadene el flujo o una de las direcciones URL de servicio globales. Si no serviceUrl 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
  • GCC High: https://smba.infra.gov.teams.microsoft.us/teams
  • DoD: https://smba.infra.dod.teams.microsoft.us/teams

Advertencia

  • Estas direcciones URL son solo para mensajes proactivos. Evite codificarlas de forma rígida. En su lugar, úselo serviceUrl de la actividad entrante o la referencia de conversación. Si no está disponible, use direcciones URL globales basadas en región y nube.

  • Para cualquier respuesta a los mensajes, use serviceURL la de la solicitud entrante. Para obtener más información, vea la propiedad Activity.ServiceUrl .

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 id. de conversación es único para cada agente dentro de un canal específico, incluso en un entorno de varios inquilinos. Este identificador garantiza que los mensajes del agente se dirijan al canal adecuado y que no se interrumpan con otros agentes o canales dentro de la misma organización o entre organizaciones diferentes.

Si no tienes el conversationId, puedes instalar la aplicación de forma proactiva mediante Graph para obtener el conversationIdarchivo .

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 app.Send() método y el conversationId para realizar una llamada API directa. Para enviar el mensaje, establezca el conversationParameters. Consulte la sección de ejemplos o use uno de los ejemplos enumerados en la sección de ejemplos de código .

Para enviar proactivamente un mensaje como respuesta a un hilo de un canal, se puede usar app.Reply() con el identificador de conversación y el identificador del mensaje raíz del hilo.

Nota:

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

Ahora que ha enviado el mensaje proactivo, debe seguir estas prácticas recomendadas al enviar mensajes proactivos para un mejor intercambio de información entre los usuarios y el agente.

Comprender quién bloqueó, silenció o desinstaló un agente

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

Con Teams, puede enviar un mensaje proactivo al agente para comprobar si un usuario ha bloqueado o desinstalado un agente. Si el agente se bloquea o se desinstala, Teams devuelve un código de 403 respuesta con un subCode: MessageWritesBlocked. Esta respuesta indica que el mensaje enviado por el agente 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 al agente.

El ejemplo de código siguiente es un ejemplo de un 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":"{\n  \"subCode\": \"MessageWritesBlocked\",\n  \"details\": \"Thread is blocked from message writes.\",\n  \"errorCode\": null,\n  \"errorSubCode\": null\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, marca su primera interacción 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 de por qué el usuario recibe el mensaje. Además, esta es la primera interacción del usuario con su 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 su aplicación. Escriba un mensaje de bienvenida claro e itere sobre el mensaje de bienvenida si no está teniendo el efecto deseado.

Un buen mensaje de bienvenida puede incluir la siguiente información:

  • Motivo del mensaje: debe quedar claro para el usuario por qué recibe el mensaje. Si el agente 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 su 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 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 del usuario en una aplicación de pestañas, use las notificaciones de la fuente de actividades en lugar de un agente. Asegúrese de que los usuarios comprendan claramente por qué han recibido una notificación. Entre los mensajes de notificación correctos se 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 que provocaron 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 los usuarios por no participar? Debe proporcionar una ruta 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.

Para actualizar o eliminar un mensaje proactivo enviado por un agente de solo notificación:

  1. Realice un seguimiento de los mensajes enviados almacenando sus identificadores de mensajes o referencias de conversación al enviar el mensaje proactivo.

  2. Use context.Api.Conversations.Activities.UpdateAsync(conversationId, activityId, updatedActivity) nuestros context.Api.Conversations.Activities.DeleteAsync(conversationId, activityId) métodos para actualizar o eliminar el mensaje original.

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. Los mensajes de la 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

Puede usar la Graph API para instalar proactivamente 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 estén en el catálogo de aplicaciones de su organización o en la tienda de Microsoft Teams.

Consulte la instalación de aplicaciones para los usuarios en la documentación de Graph y la instalación proactiva del agente y la mensajería en Teams con Graph.

Ejemplos

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

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

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

  • API de 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 agent}/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é lo activity ID devuelto por la llamada postal original. Si la llamada se realiza correctamente, la API devuelve el siguiente objeto de respuesta:

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

Muestras

En el código siguiente se muestra cómo enviar mensajes proactivos mediante el SDK de Teams (biblioteca de IA de Teams):

// Save the conversation ID and schedule a proactive reminder on install
teams.OnInstall(async (context, cancellationToken) =>
{
    context.Storage.Set(context.Activity.From.AadObjectId!, context.Activity.Conversation.Id);
    await context.Send("Hi! I am going to remind you to say something to me soon!", cancellationToken);
    notificationQueue.AddReminder(context.Activity.From.AadObjectId!, Notifications.SendProactive, 10_000);
});
 
// Send proactive message using stored conversation ID
public static class Notifications
{
    public static async Task SendProactive(string userId)
    {
        var conversationId = (string?)storage.Get(userId);
        if (conversationId is null) return;
        await app.Send(conversationId, "Hey! It's been a while. How are you?");
    }
}

Ejemplos de código

En la tabla siguiente se proporcionan ejemplos de código que incorporan el flujo de conversación básico y la mensajería proactiva en una aplicación de Teams con el SDK de Teams:

Nombre de ejemplo Descripción .NET Node.js Python Manifiesto
Conceptos básicos de conversación de Teams En esta aplicación de ejemplo se muestra cómo usar diferentes eventos de conversación de agente disponibles en el SDK de Teams v2 para el ámbito personal y de equipos. View View View View
Bot Mensaje proactivo En este ejemplo se muestra cómo capturar y almacenar un identificador de conversación de una actividad de instalación y usarlo para enviar mensajes proactivos inmediatos y con retraso a un usuario. View View View ND

Pasos siguientes

Dar formato a mensajes de agente

Vea también

  • Last updated on