Mensajes en conversaciones de bot
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:
- Agregue el permiso RSC
ChatMessageReadReceipt.Read.Chaten el manifiesto de la aplicación, como se indica a continuación:
"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
OnTeamsReadReceiptAsyncconIsMessageReadel controlador .El
IsMessageReadmétodo auxiliar es útil para determinar si los destinatarios leen el mensaje. Si escompareMessageIdmenor o igual que ,LastReadMessageIdse ha leído el mensaje. Invalide elOnTeamsReadReceiptAsyncmétodo para recibir recibos de lectura conIsMessageReadel 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 permiten al bot presentar botones que el usuario puede seleccionar para proporcionar entrada. Las acciones sugeridas mejoran la experiencia del usuario al permitir que el usuario responda a una pregunta o haga una elección con la selección de un botón, en lugar de escribir una respuesta con un teclado. Cuando el usuario selecciona un botón, permanece visible y accesible en las tarjetas enriquecidas, pero no para las acciones sugeridas. Esto impide que el usuario seleccione botones obsoletos dentro de una conversación.
Para agregar acciones sugeridas a un mensaje, establezca la suggestedActions propiedad de un objeto de actividad para especificar la lista de objetos de acción de tarjeta que representan los botones que se van a presentar al usuario. Para más información, vea sugestedActions.
A continuación se muestra un ejemplo de implementación y experiencia de acciones sugeridas:
"suggestedActions": {
"actions": [
{
"type": "imBack",
"title": "Action 1",
"value": "Action 1"
},
{
"type": "imBack",
"title": "Action 2",
"value": "Action 2"
}
],
"to": [<list of recepientIds>]
}
A continuación se muestra un ejemplo de acciones sugeridas:
Nota:
SuggestedActionssolo se admiten para bots de chat uno a uno con mensajes basados en texto y tarjetas adaptables.SuggestedActionsno se admiten para bots de chat con datos adjuntos para cualquier tipo de conversación.imBackes el único tipo de acción admitido y Teams muestra hasta seis 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.id: GUID para el canal.name: nombre del equipo pasado solo en los casos de eventos de cambio de nombre del equipo.
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.id: GUID para el canal.name: el nombre del canal solo se pasa en los casos de eventos de modificación del canal.
channelData.teamsTeamId:Obsoleto. Esta propiedad solo se incluye por compatibilidad con versiones anteriores.channelData.teamsChannelId:Obsoleto. 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 actualmente 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:
.
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.Alertmensaje 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. | Sí | 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. | Sí | 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. | Sí | 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 | View |
| 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 | View | ND |
Paso siguiente
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de