Compartir a través de

Mensajes en conversaciones de bot

  • Artículo

Cada mensaje de una conversación es un Activity objeto de tipo messageType: message. Cuando un usuario envía un mensaje, Microsoft Teams publica la actividad del mensaje en el bot. Teams envía un objeto JSON al punto de conexión de mensajería del bot y Teams solo permite un punto de conexión para la mensajería. El bot examina el mensaje para determinar su tipo y responder correctamente.

Las conversaciones básicas se controlan a través del conector de Bot Framework, una única API REST. Esta API permite que el bot se comunique con Teams y otros canales. El SDK de Bot Builder proporciona las siguientes características:

  • Fácil acceso al conector de Bot Framework.
  • Funcionalidad para administrar el flujo y el estado de la conversación.
  • Formas sencillas de incorporar servicios cognitivos, como el procesamiento de lenguaje natural (NLP).

El bot recibe mensajes de Teams mediante la Text propiedad y envía una o varias respuestas de mensaje a los usuarios.

Para obtener más información, consulte atribución de usuarios para mensajes de bot.

En la tabla siguiente se muestra la actividad en la que el bot puede recibir y realizar acciones:

Tipo Objeto de carga Ámbito
Recepción de una actividad de mensaje Actividad de mensaje todas
Recepción de la actividad de edición de mensajes Actividad de edición de mensajes todas
Recepción de la actividad de recuperación de mensajes Actividad de recuperación de mensajes todas
Recepción de la actividad de mensajes de eliminación temporal Actividad de eliminación temporal de mensajes todas

Recepción de una actividad de mensaje

Para recibir un mensaje de texto, use la Text propiedad de un Activity objeto . En el controlador de actividades del bot, use convertir Activity del objeto de contexto para leer una solicitud de mensaje única.

El código siguiente muestra un ejemplo de recepción de una actividad de mensaje:


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}

Recepción de un recibo de lectura

La configuración Leer recibos de Teams permite que el remitente de un mensaje de chat reciba una notificación cuando el destinatario leyó el mensaje en chats individuales y grupales. Una vez que el destinatario lee el mensaje, aparece visto junto al mensaje. También tiene la opción de configurar el bot para recibir eventos de recepción de lectura mediante la configuración Read receipts (Recibos de lectura). El evento de recepción de lectura ayuda a mejorar la experiencia del usuario de las siguientes maneras:

  • Puede configurar el bot para enviar un mensaje de seguimiento si el usuario de la aplicación no ha leído el mensaje en el chat personal.

  • Puede crear un bucle de comentarios mediante recibos de lectura para optimizar la experiencia del bot.

Nota:

  • Los recibos de lectura solo se admiten en escenarios de chat de usuarios a bots.
  • Los recibos de lectura de los bots no admiten ámbitos de chat de grupo, canal y equipo.
  • Si un administrador de inquilinos o un usuario deshabilita la configuración Leer recibos , el bot no recibe el evento de recepción de lectura.

Para recibir eventos de recibos de lectura para el bot, asegúrese de lo siguiente:

    
"webApplicationInfo": {
    
     "id": "38f0ca43-1c38-4c39-8097e-47f62c686500",
     "resource": ""
},
"authorization": {
    "permissions": {
    "orgwide": [],
     "resourceSpecific": [
        {
        "name": "ChatMessageReadReceipt.Read.Chat",
        "type": "Application"
        }
        ]
     }
 }

También puede agregar permisos de RSC a través de Graph API. Para más información, vea consentedPermissionSet.

  • Invalide el método OnTeamsReadReceiptAsync con IsMessageRead el controlador .

    El IsMessageRead método auxiliar es útil para determinar si los destinatarios leen el mensaje. Si es compareMessageId menor o igual que , LastReadMessageIdse ha leído el mensaje. Invalide el OnTeamsReadReceiptAsync método para recibir recibos de lectura con IsMessageRead el método auxiliar:

    
protected override async Task OnTeamsReadReceiptAsync(ReadReceiptInfo readReceiptInfo, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken) 
{
    var lastReadMessageId = readReceiptInfo.LastReadMessageId;
   if (IsMessageRead("{id of the message that you care}", LastReadMessageId))
   {
        await turnContext.SendActivityAsync(MessageFactory.Text("User read the bot's message"), cancellationToken);    
    }
}

    A continuación se muestra un ejemplo de solicitud de evento de recibos de lectura que recibe un bot:

    {
    "name": "application/vnd.microsoft.readReceipt",
    "type": "event",
    "timestamp": "2023-08-16T17:23:11.1366686Z",
    "id": "f:b4783e72-9d7b-2ed9-ccef-ab446c873007",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1-8Iuh70W9pRqV8tQK8o2nVjxz33RRGDKLf4Bh7gKnrzN8s7e4vCyrFwjkPbTCX_Co8c4aXwWvq3RBLr-WkkVMw",
        "aadObjectId": "5b649834-7412-4cce-9e69-176e95a394f5"
    },
    "conversation": {
        "conversationType": "personal",
        "tenantId": "6babcaad-604b-40ac-a9d7-9fd97c0b779f",
        "id": "a:1xlimp68NSUxEqK0ap2rXuwC9ITauHgV2M4RaDPkeRhV8qMaFn-RyilMZ62YiVdqs8pp43yQaRKvv_U2S2gOS5nM-y_pOxVe4BW1qMGPtqD0Bv3pw-nJXF0zhDlZHMZ1Z"
    },
    "recipient": {
        "id": "28:9901a8b6-4fef-428b-80b1-ddb59361adeb",
        "name": "Test Bot"
    },
    "channelData": {
        "tenant": {
            "id": "6babcaad-604b-40ac-a9d7-9fd97c0b779f"
        }
    },
    "value": {
        "lastReadMessageId": "1692206589131"
    }
}

  • La configuración del administrador de recibos de lectura o la configuración de usuario están activadas para que el inquilino reciba los eventos de recepción de lectura. El administrador de inquilinos o el usuario deben habilitar o deshabilitar la configuración de recibo de lectura.

Una vez habilitado el bot en un escenario de chat de usuario a bot, el bot recibe rápidamente un evento de recibo de lectura cuando el usuario lee el mensaje del bot. Puede realizar un seguimiento de la interacción del usuario contando el número de eventos y también puede enviar un mensaje contextual.

Enviar un mensaje

Para enviar un mensaje de texto, especifique la cadena que desea enviar como actividad. En el controlador de actividad del bot, use el método del objeto de contexto turn SendActivityAsync para enviar una única respuesta de mensaje. Use el método del SendActivitiesAsync objeto para enviar varias respuestas.

En el código siguiente se muestra un ejemplo de envío de un mensaje cuando se agrega un usuario a una conversación:


protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}

Nota:

  • La división de mensajes se produce cuando se envían un mensaje de texto y datos adjuntos en la misma carga de actividad. Teams divide esta actividad en dos actividades independientes, una con un mensaje de texto y la otra con datos adjuntos. A medida que se divide la actividad, no recibe el identificador de mensaje en respuesta, que se usa para actualizar o eliminar el mensaje de forma proactiva. Se recomienda enviar actividades independientes en lugar de depender de la división de mensajes.
  • Los mensajes enviados se pueden localizar para proporcionar personalización. Para obtener más información, consulte Localización de la aplicación.

Los mensajes enviados entre usuarios y bots incluyen datos de canal internos dentro del mensaje. Estos datos permiten que el bot se comunique correctamente en ese canal. El SDK de Bot Builder permite modificar la estructura del mensaje.

Obtener actividad de edición de mensajes

Al editar un mensaje, el bot recibe una notificación de la actividad de edición del mensaje.

Para obtener una notificación de actividad de mensaje de edición en un bot, puede invalidar el OnTeamsMessageEditAsync controlador.

A continuación se muestra un ejemplo de una notificación de actividad de edición de mensajes mediante OnTeamsMessageEditAsync cuando se edita un mensaje enviado:


protected override async Task OnTeamsMessageEditAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken) 
{ 
var replyActivity = MessageFactory.Text("message is updated"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
}

Obtención de la actividad de recuperación de mensajes

Al recuperar un mensaje, el bot recibe una notificación de la actividad de recuperación del mensaje.

Para obtener una notificación de actividad de mensaje de recuperación en un bot, puede invalidar el OnTeamsMessageUndeleteAsync controlador.

A continuación se muestra un ejemplo de una notificación de actividad de recuperación de mensajes mediante OnTeamsMessageUndeleteAsync cuando se restaura un mensaje eliminado:


protected override async Task OnTeamsMessageUndeleteAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{ 
var replyActivity = MessageFactory.Text("message is undeleted"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
}

Obtención de la actividad de eliminación temporal de mensajes

Al eliminar temporalmente un mensaje, el bot recibe una notificación de la actividad de mensaje de eliminación temporal.

Para obtener una notificación de actividad de mensaje de eliminación temporal en un bot, puede invalidar el OnTeamsMessageSoftDeleteAsync controlador.

A continuación se muestra un ejemplo de una notificación de actividad de mensaje de eliminación temporal mediante OnTeamsMessageSoftDeleteAsync cuando se elimina temporalmente un mensaje:


protected override async Task OnTeamsMessageSoftDeleteAsync(ITurnContext<IMessageDeleteActivity> turnContext, CancellationToken cancellationToken) 
{ 
var replyActivity = MessageFactory.Text("message is soft deleted"); 
await turnContext.SendActivityAsync(replyActivity, cancellationToken); 
}

Envío de acciones sugeridas

Las acciones sugeridas ayudan a los usuarios con ideas sobre qué preguntar a continuación, en función de la respuesta o la conversación anteriores. El bot debe ofrecer sugerencias específicas del contexto al usuario, en lugar de genéricas o fijas. Puede usar el modelo de lenguaje grande (LLM) del bot para generar hasta tres sugerencias junto con sus respuestas. A continuación, puede extraer estas sugerencias y presentarlas como opciones para que el usuario elija.

Cuando un usuario selecciona un botón, permanece visible y accesible en las tarjetas enriquecidas. Sin embargo, para las acciones sugeridas, los botones están diseñados para desaparecer después de la selección para evitar que el usuario seleccione opciones obsoletas que pueden dejar de ser pertinentes.

Nota:

  • SuggestedActions solo se admiten para bots de chat uno a uno con mensajes basados en texto y tarjetas adaptables.
  • SuggestedActions no se admiten para bots de chat con datos adjuntos para cualquier tipo de conversación.
  • imBack es el único tipo de acción admitido y Teams muestra hasta tres acciones sugeridas.

Para agregar acciones sugeridas a un mensaje, especifique una lista de objetos de acción de tarjeta que representen los botones que se mostrarán al usuario para la sugestedActions propiedad del objeto de actividad .

A continuación se muestra un ejemplo para implementar y experimentar acciones sugeridas:

{
  "type": "message",
  "from": {
    "id": "12345678",
    "name": "sender's name"
  },
  "conversation": {
    "id": "abcd1234",
    "name": "conversation's name"
  },
  "recipient": {
    "id": "1234abcd",
    "name": "recipient's name"
  },
  "text": "What are the tasks for the day.",
  "inputHint": "expectingInput",
  "suggestedActions": {
    "actions": [
      {
        "type": "imBack",
        "title": "Create a new query identifying overdue tasks",
        "value": "Create a new query identifying overdue tasks"
      },
      {
        "type": "imBack",
        "title": "Create a new work item for this feature",
        "value": "Create a new work item for this feature"
            }
        ]
    },
  "replyToId": "5d5cdc723"
}

A continuación se muestra un ejemplo de acciones sugeridas:

Datos del canal de Teams

El channelData objeto contiene información específica de Teams y es un origen definitivo para los identificadores de equipo y canal. Opcionalmente, puede almacenar en caché y usar estos identificadores como claves para el almacenamiento local. en TeamsActivityHandler el SDK extrae información importante del channelData objeto para que sea accesible. Sin embargo, siempre puede acceder a los datos originales desde el turnContext objeto .

El channelData objeto no se incluye en los mensajes de las conversaciones personales, ya que tienen lugar fuera de un canal.

Un objeto típico channelData de una actividad enviada al bot contiene la siguiente información:

  • eventType: el tipo de evento de Teams solo se pasa en los casos de eventos de modificación del canal.
  • tenant.id: Microsoft Entra identificador de inquilino pasado en todos los contextos.
  • team: solo se pasa en contextos de canal, no en chat personal.
  • channel: solo se pasa en contextos de canal, cuando se menciona el bot o para eventos en canales de teams, donde se agrega el bot.
  • channelData.teamsTeamId:Obsolescente. Esta propiedad solo se incluye por compatibilidad con versiones anteriores.
  • channelData.teamsChannelId:Obsolescente. Esta propiedad solo se incluye por compatibilidad con versiones anteriores.

Ejemplo de objeto channelData

En el código siguiente se muestra un ejemplo de objeto channelData (evento channelCreated):

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

Contenido del mensaje

Los mensajes recibidos o enviados al bot pueden incluir diferentes tipos de contenido de mensaje.

Formato De usuario a bot De bot a usuario Notas
Texto enriquecido ✔️ ✔️ El bot puede enviar texto enriquecido, imágenes y tarjetas. Los usuarios pueden enviar texto enriquecido e imágenes al bot.
Imágenes ✔️ ✔️ Máximo 1024 × 1024 píxeles y 1 MB en formato PNG, JPEG o GIF. No admite el GIF animado.
Tarjetas ❌ ✔️ Consulte Referencia de tarjetas de Teams para obtener las tarjetas admitidas.
Emojis ✔️ ✔️ Teams admite emojis a través de UTF-16, como U+1F600 para la cara sonriente.

Mensajes de imagen

Para mejorar el mensaje, puede incluir imágenes como datos adjuntos a ese mensaje. Para obtener más información sobre los datos adjuntos, vea Agregar datos adjuntos multimedia a los mensajes.

Las imágenes pueden tener como máximo 1024 × 1024 píxeles y 1 MB en formato PNG, JPEG o GIF. No se admite el uso de un GIF animado.

Especifique el alto y el ancho de cada imagen mediante XML. En Markdown, el tamaño predeterminado de la imagen es 256×256. Por ejemplo:

  • Use: <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>.
  • No use: ![Duck on a rock](http://aka.ms/Fo983c).

Un bot conversacional puede incluir tarjetas adaptables que simplifican los flujos de trabajo empresariales. Las tarjetas adaptables ofrecen texto personalizable enriquecido, voz, imágenes, botones y campos de entrada.

Tarjetas adaptables

Las tarjetas adaptables se pueden crear en un bot y mostrarse en varias aplicaciones, como Teams, su sitio web, etc. Para obtener más información, vea Tarjetas adaptables.

En el código siguiente se muestra un ejemplo de envío de una tarjeta adaptable simple:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
    {
        "items": [
        {
            "size": "large",
            "text": " Simple Adaptivecard Example with a Textbox",
            "type": "TextBlock",
            "weight": "bolder",
            "wrap": true
        },
        ],
        "spacing": "extraLarge",
        "type": "Container",
        "verticalContentAlignment": "center"
    }
    ]
}

Adición de notificaciones al mensaje

Hay dos maneras de enviar una notificación desde la aplicación:

  • Al establecer la propiedad en el Notification.Alert mensaje del bot.
  • Mediante el envío de una notificación de fuente de actividad mediante el Graph API.

Puede agregar notificaciones al mensaje mediante la Notification.Alert propiedad . Las notificaciones alertan a los usuarios de un evento en la aplicación, como nuevas tareas, menciones o comentarios. Estas alertas están relacionadas con lo que los usuarios están trabajando o con lo que deben examinar insertando un aviso en su fuente de actividad. Para que las notificaciones se desencadenen desde el mensaje del bot, establezca la TeamsChannelData propiedad objects Notification.Alert en true. Si se genera una notificación depende de la configuración de Teams del usuario individual y no puede invalidar esta configuración.

Si desea generar una notificación arbitraria sin enviar un mensaje al usuario, puede usar el Graph API. Para obtener más información, consulte cómo enviar notificaciones de fuente de actividad mediante Graph API junto con los procedimientos recomendados.

Nota:

El campo Resumen muestra cualquier texto del usuario como mensaje de notificación en la fuente.

En el código siguiente se muestra un ejemplo de cómo agregar notificaciones al mensaje:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Returns a simple text message.
  var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
  message.TeamsNotifyUser();

  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(message);
}

Códigos de estado de las API conversacionales del bot

Asegúrese de controlar estos errores correctamente en la aplicación de Teams. En la tabla siguiente se enumeran los códigos de error y las descripciones con las que se generan los errores:

Código de estado Código de error y valores de mensaje Descripción Solicitud de reintento Acción del desarrollador
400 Código: Bad Argument
Mensaje: *específico del escenario		 Carga de solicitud no válida proporcionada por el bot. Consulte el mensaje de error para obtener detalles específicos. No Vuelva a evaluar la carga de la solicitud para los errores. Compruebe el mensaje de error devuelto para obtener más información.
401 Código: BotNotRegistered
Mensaje: No se encontró ningún registro para este bot.		 No se encontró el registro de este bot. No Compruebe el identificador y la contraseña del bot. Asegúrese de que el identificador del bot (Microsoft Entra ID) está registrado en el Portal para desarrolladores de Teams o a través del registro del canal del bot de Azure en Azure con el canal "Teams" habilitado.
403 Código: BotDisabledByAdmin
Mensaje: El administrador de inquilinos deshabilitó este bot		 El administrador de inquilinos bloqueó las interacciones entre el usuario y la aplicación del bot. El administrador de inquilinos debe permitir la aplicación para el usuario dentro de las directivas de la aplicación. Para obtener más información, consulte Directivas de aplicación. No Deje de publicar en la conversación hasta que un usuario inicie explícitamente la interacción con el bot en la conversación, lo que indica que el bot ya no está bloqueado.
403 Código: BotNotInConversationRoster
Mensaje: El bot no forma parte de la lista de conversaciones.		 El bot no forma parte de la conversación. La aplicación debe volver a instalarse en la conversación. No Antes de intentar enviar otra solicitud de conversación, espere un installationUpdate evento, lo que indica que el bot se agrega de nuevo.
403 Código: ConversationBlockedByUser
Mensaje: El usuario bloqueó la conversación con el bot.		 El usuario bloqueó el bot en un chat personal o un canal a través de la configuración de moderación. No Elimine la conversación de la memoria caché. Deje de intentar publicar en las conversaciones hasta que un usuario inicie explícitamente la interacción con el bot en la conversación, lo que indica que el bot ya no está bloqueado.
403 Código: ForbiddenOperationException
Mensaje: El bot no está instalado en el ámbito personal del usuario		 Un bot envía un mensaje proactivo, que no está instalado en un ámbito personal. No Antes de intentar enviar otra solicitud de conversación, instale la aplicación en el ámbito personal.
403 Código: InvalidBotApiHost
Mensaje: Host de api de bot no válido. Para los inquilinos de GCC, llame a https://smba.infra.gcc.teams.microsoft.com.		 El bot llamó al punto de conexión de API público para una conversación que pertenece a un inquilino de GCC. No Actualice la dirección URL del servicio de la conversación a y vuelva a https://smba.infra.gcc.teams.microsoft.com intentar la solicitud.
403 Código: NotEnoughPermissions
Mensaje: *específico del escenario		 El bot no tiene los permisos necesarios para realizar la acción solicitada. No Determine la acción necesaria del mensaje de error.
404 Código: ActivityNotFoundInConversation
Mensaje: No se encontró la conversación.		 No se encontró el identificador de mensaje proporcionado en la conversación. El mensaje no existe o se elimina. No Compruebe si el identificador de mensaje enviado es un valor esperado. Quite el identificador si se ha almacenado en caché.
404 Código: ConversationNotFound
Mensaje: No se encontró la conversación.		 No se encontró la conversación, ya que no existe o se elimina. No Compruebe si el identificador de conversación enviado es un valor esperado. Quite el identificador si se ha almacenado en caché.
412 Código: PreconditionFailed
Mensaje: Error de condición previa, inténtelo de nuevo.		 Error de condición previa en una de nuestras dependencias debido a varias operaciones simultáneas en la misma conversación. Yes Vuelva a intentarlo con retroceso exponencial.
413 Código: MessageSizeTooBig
Mensaje: tamaño del mensaje demasiado grande.		 El tamaño de la solicitud entrante era demasiado grande. Para obtener más información, consulte Dar formato a los mensajes del bot. No Reduzca el tamaño de la carga.
429 Código: Throttled
Mensaje: Demasiadas solicitudes. También devuelve cuándo volver a intentarlo después.		 Demasiadas solicitudes enviadas por el bot. Para obtener más información, consulte límite de velocidad. Yes Vuelva a intentar usar el Retry-After encabezado para determinar el tiempo de retroceso.
500 Código: ServiceError
Mensaje: *varios		 Error interno del servidor. No Informe del problema en la comunidad de desarrolladores.
502 Código: ServiceError
Mensaje: *varios		 Problema de dependencia de servicio. Yes Vuelva a intentarlo con retroceso exponencial. Si el problema persiste, informe del problema en la comunidad de desarrolladores.
503 El servicio no está disponible. Yes Vuelva a intentarlo con retroceso exponencial. Si el problema persiste, informe del problema en la comunidad de desarrolladores.
504 Tiempo de espera de la puerta de enlace. Yes Vuelva a intentarlo con retroceso exponencial. Si el problema persiste, informe del problema en la comunidad de desarrolladores.

Guía de reintento de códigos de estado

La guía general de reintentos para cada código de estado se muestra en la tabla siguiente; el bot debe evitar reintentar los códigos de estado que no se especifican:

Código de estado Estrategia de reintento
403 Vuelva a intentarlo llamando a la API https://smba.infra.gcc.teams.microsoft.com de GCC para InvalidBotApiHost.
412 Vuelva a intentarlo con el retroceso exponencial.
429 Vuelva a intentar usar Retry-After el encabezado para determinar el tiempo de espera en segundos y entre solicitudes, si está disponible. De lo contrario, vuelva a intentar usar el retroceso exponencial con el identificador de subproceso, si es posible.
502 Vuelva a intentarlo con el retroceso exponencial.
503 Vuelva a intentarlo con el retroceso exponencial.
504 Vuelva a intentarlo con el retroceso exponencial.

Ejemplo de código

Ejemplo de nombre Descripción Node.js .NETCore Python .NET Manifiesto
Bot 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. View View Ver ND Ver
Localización de aplicaciones de Teams En este ejemplo se muestra la localización de aplicaciones de Teams mediante bot y pestaña. Ver ND ND Ver ND

Paso siguiente

Menús de comandos del bot

Vea también