Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Con la mensajería dirigida, los usuarios y los agentes pueden interactuar de forma privada sin distraer a otros usuarios ni exponer información que no está pensada para el grupo. Considere los escenarios siguientes:
- Un usuario puede pedir a un agente que genere un resumen de la discusión sin que los demás participantes vean la solicitud o la respuesta.
- Un usuario puede solicitar información de forma privada a un agente con la intención de compartirlo con el grupo, pero quiere confirmar primero el contenido del mensaje. El agente puede responder de forma privada, con una acción sugerida que solicita la aprobación del usuario para compartir su respuesta. Cuando el usuario lo aprueba, el agente vuelve a enviar el mensaje públicamente. Para obtener más información, consulte procedimientos recomendados e instrucciones de diseño.
- Un usuario puede dirigir y supervisar el trabajo en segundo plano con agentes, haciendo referencia al contexto de la conversación, sin distraer a los demás participantes.
- Un agente puede detectar un nuevo usuario que entra en una conversación grande y de larga duración y enviarle de forma proactiva un mensaje de bienvenida privado y un resumen.
Importante
La mensajería dirigida es una parte fundamental del diseño del agente para las conversaciones en grupo y requiere un control cuidadoso de las expectativas de privacidad del usuario. Para obtener más información, consulte procedimientos recomendados e instrucciones de diseño.
Aspectos clave de los mensajes de destino
Mensajes de destino:
- Solo se puede usar para interacciones uno a uno entre un agente y un usuario en canales, chats de grupo y chats de reuniones.
- Admite todas las funcionalidades de mensajes estándar , como botones, imágenes, tarjetas adaptables y archivos, pero no admite reacciones, respuestas ni reenvíos.
- Por lo general, funcionan de la misma manera que los mensajes estándar, con las mismas operaciones de API. Los usuarios y agentes pueden modificar o eliminar mensajes de destino después de enviarlos, pero no pueden cambiar su visibilidad. Si un escenario llama a que un mensaje privado se haga público, el remitente debe eliminarlo y reenviarlo como un mensaje estándar; consulte procedimientos recomendados e instrucciones de diseño.
- Expire 24 horas después de su envío. Cuando expira un mensaje de destino, Teams lo elimina de todos los clientes, aunque podría conservarse en un almacenamiento seguro en función de la directiva de la organización.
- No son visibles para los usuarios no dirigidos, incluso si usan una versión anterior del cliente de Teams que no admite mensajes de destino.
Experiencia del usuario
Los mensajes dirigidos enviados o recibidos por un usuario se presentan en el flujo de la conversación con un indicador que indica Solo usted puede ver este mensaje.
Los usuarios envían mensajes de destino a un agente en un canal, chat en grupo o chat de reunión invocando su nombre como un comando de barra diagonal.
Cuando un usuario escribe en un / cuadro de redacción vacío, Teams muestra un menú autocompletar que contiene comandos integrados para tareas comunes. Si la conversación incluye agentes que son aptos para recibir mensajes de destino, el menú también incluirá un comando de mensaje de destino para cada uno de ellos, con el nombre del agente y mostrando su icono.
Al activar el comando de mensaje de destino de un agente, se cambia el cuadro de redacción al modo de mensaje de destino. Una vez que el usuario redacta un mensaje y selecciona Enviar, el mensaje resultante se dirigirá al agente y otros participantes no podrán verlo en la conversación.
Para obtener más información sobre los comandos de barra diagonal, incluido cómo registrar comandos de barra diagonal con nombre adicionales que se pueden enviar al agente, vea Exponer comandos de barra diagonal de agentes y aplicaciones.
Solicitud de vista previa en mensajes de destino
Prompt Preview ayuda a conservar el contexto conversacional en escenarios de mensajería de destino mediante la visualización de una vista previa compacta de la solicitud original del usuario sobre la respuesta del agente. Prompt Preview ayuda a los usuarios a comprender el contexto de una respuesta sin exponer el mensaje original a otros participantes. Una única respuesta del agente puede contener varias vistas previas del símbolo del sistema.
La vista previa del aviso puede aparecer en las respuestas del agente público y privado:
El agente responde de forma privada al mensaje de destino del usuario, por lo que solo el usuario previsto puede ver la respuesta y la vista previa del mensaje.
Respuestas entre comillas en mensajes dirigidos
Las respuestas entre comillas hacen referencia a un mensaje anterior en un subproceso, lo que ayuda a los lectores a identificar lo que se relaciona con una respuesta y a volver al contexto original. Use una respuesta entre comillas al responder a un punto anterior en un subproceso ocupado o cuando es posible que los lectores necesiten volver al mensaje al que se hace referencia. Las respuestas entre comillas admiten la navegación por subprocesos, mientras que Prompt Preview conserva la relación de solicitud-respuesta privada para las respuestas del agente de destino y el uso compartido basado en la aprobación.
Para obtener más información, consulte respuestas entre comillas.
Implementación de mensajes de destino
Los mensajes de destino se envían y reciben con las mismas operaciones que los mensajes de un solo destinatario estándar en el SDK de Teams, pero tienen una propiedad booleana que indica si están dirigidos.
Recepción de mensajes de destino
Un agente debe participar a través de su manifiesto para poder recibir mensajes de destino. Si no se ha optado, Teams no dará a los usuarios la opción de enviar un mensaje de destino al agente.
Los agentes que optan por recibir mensajes de destino siempre deben comprobar la visibilidad de los mensajes que reciben y tenerla en cuenta al generar respuestas y realizar un seguimiento del contexto de una conversación. Para obtener más información, consulte procedimientos recomendados e instrucciones de diseño.
Para participar en la recepción de mensajes de destino, establezca supportsTargetedMessages la propiedad true en en la entrada del agente en el manifiesto de botsla aplicación.
{
"bots": [
{
"botId": "{{BOT_ID}}",
"scopes": ["personal", "team", "groupChat"],
"supportsTargetedMessages": true
}
]
}
Los agentes reciben mensajes a través de eventos de mensaje estándar. Los mensajes de destino se pueden distinguir de los mensajes públicos, como se muestra en el siguiente fragmento de código:
app.on('message', async ({ send, activity }) => {
if(activity.Recipient.isTargeted) {
// Handle message event
}
});
teams.OnMessage(async (context, cancellationToken) => {
if (context.Activity.Recipient?.IsTargeted == true){
// Handle message event
}
});
@app.on_message
async def handle_message(ctx):
if getattr(ctx.activity.recipient, "is_targeted", False):
# Handle message event
Envío de un mensaje de destino
Todos los agentes de Teams son aptos automáticamente para enviar mensajes de destino. Para enviar un mensaje de destino, use withRecipient para especificar un único destinatario por su identificador y proporcione un valor de true para el isTargeted argumento . El destinatario debe ser miembro del chat o canal.
import { MessageActivity } from '@microsoft/teams.api';
app.on('message', async ({ send, activity }) => {
// Using withRecipient with isTargeted=true explicitly targets the specified recipient
await send(
new MessageActivity('This message is only visible to you!')
.withRecipient(activity.from, true)
);
});
app.OnMessage(async context =>
{
// Using WithRecipient with isTargeted=true explicitly targets the specified recipient
await context.Send(
new MessageActivity("This message is only visible to you!")
.WithRecipient(context.Activity.From, isTargeted: true)
);
});
from microsoft_teams.api import MessageActivity, MessageActivityInput
from microsoft_teams.apps import ActivityContext
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
# Using with_recipient with is_targeted=True explicitly targets the specified recipient
await ctx.send(
MessageActivityInput(text="This message is only visible to you!")
.with_recipient(ctx.activity.from_, is_targeted=True)
)
Nota:
Si al intentar enviar un mensaje de destino se produce un error, considere la posibilidad de enviar un mensaje de chat 1:1 como reserva.
Integración de la vista previa del símbolo del sistema en un mensaje de destino
Prompt Preview puede aparecer en las respuestas del agente público y privado, pero el mecanismo de implementación es el mismo en ambos casos: el agente incluye que hace targetedMessageInfo referencia al mensaje de destino original. La diferencia es solo quién puede ver la respuesta después de enviarla.
La versión preliminar del símbolo del sistema se admite automáticamente en escenarios reactivos , como cuando un agente responde al mensaje de destino de un usuario o a la solicitud de comando de barra diagonal mediante send() o a través del SDK de reply() Teams o la API REST. En estos casos, el SDK normalmente agrega la targetedMessageInfo entidad automáticamente, vinculando la respuesta a la solicitud de usuario original.
En escenarios proactivos , la respuesta se envía fuera del turno de conversación original. Como resultado, el agente debe incluir explícitamente la targetedMessageInfo entidad y proporcionar el identificador de mensaje de destino antes de enviar el mensaje privado o público.
Esto garantiza que la respuesta permanece asociada a la solicitud original correcta y permite que Prompt Preview muestre el símbolo del sistema adecuado.
Para representar la vista previa del mensaje, incluya una targetedMessageInfo entidad en la actividad de respuesta y establezca su messageId valor en el identificador de mensaje del mensaje de destino original, que Teams usa para mostrar la solicitud original del usuario sobre la respuesta del agente, como se muestra en este ejemplo:
if (isTargeted) {
response.addTargetedMessageInfo(targetedMessageId);
}
if (isTargeted)
{
response.AddTargetedMessageInfo(targetedMessageId);
}
if is_targeted:
response.add_targeted_message_info(activity.id)
Envío de respuestas mediante las API REST
Si va a enviar respuestas a través de las API REST, use la misma targetedMessageInfo entidad en la carga de actividad.
POST {cloud}/v3/conversations/{conversationId}/activities?isTargetedActivity=true
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json
JSON
{
"type": "message",
"from": {
"id": "28:c9e...",
"name": "Contoso"
},
"conversation": {
"id": "x:17I0...",
"name": "Convo1"
},
"recipient": {
"id": "29:1XJ...",
"name": "Megan Bowen"
},
"text": "My agent's reply",
"entities": [
{
"type": "targetedMessageInfo",
"messageId": "1772129782775"
}
]
}
Use isTargetedActivity=true para la respuesta privada. Para una repostación pública, envíe el mensaje con normalidad, pero mantenga la misma targetedMessageInfo entidad.
Para representar la vista previa del mensaje, incluya una targetedMessageInfo entidad en la actividad de respuesta y establezca su messageId valor en el identificador de mensaje del mensaje de destino original para mostrar la solicitud original del usuario sobre la respuesta del agente, como se muestra en este ejemplo:
"entities": [{
"type": "targetedMessageInfo",
"messageId": "xxxxxxxxxxxxx"
}]
En este ejemplo se agrega una targetedMessageInfo entidad type a la matriz de la entities actividad y se hace referencia al mensaje de usuario original a través de su messageId. Esta asociación habilita Prompt Preview y permite que la solicitud original aparezca encima de la respuesta del agente.
Actualización o eliminación de un mensaje de destino
Los mensajes de destino se pueden actualizar y eliminar de la misma manera que los mensajes estándar, con las siguientes limitaciones:
- No se puede cambiar la visibilidad de un mensaje de destino.
- Los mensajes de destino expiran después de 24 horas y se eliminan automáticamente de los clientes. Al intentar modificar o eliminar un mensaje expirado, se produce un error.
Para obtener más información sobre cómo actualizar o eliminar un mensaje de destino, consulte SDK de Teams.
Flujo de trabajo de aprobación mediante acciones sugeridas
La aprobación de usuarios es una medida de seguridad clave en los flujos de trabajo de mensajería de destino. Dado que la respuesta de un agente puede contener información específica del usuario, se requiere el consentimiento explícito del usuario antes de compartirlo en una conversación pública.
El agente puede responder de forma privada, con una acción sugerida que solicita la aprobación del usuario para compartir su respuesta. Cuando el usuario lo aprueba, el agente vuelve a enviar el mensaje públicamente. La experiencia de aprobación se puede implementar a través de superficies de revisión interactivas, como tarjetas adaptables o acciones sugeridas. Este es un flujo de trabajo de aprobación de usuario recomendado:
- Recibir la solicitud de destino del usuario.
- Envíe la respuesta del agente de forma privada, incluida una vista previa del mensaje para el contexto.
- Presentar opciones de aprobación mediante Acciones sugeridas o una tarjeta adaptable.
- Publique la respuesta a la conversación solo después de que el usuario apruebe el uso compartido.
Las acciones recomendadas pueden incluir Aprobar, Rechazar, Compartir y Actualizar.
Procedimientos recomendados e instrucciones de diseño
La capacidad de los usuarios y agentes para comunicarse de forma privada con la mensajería de destino es una consideración fundamental en las conversaciones en grupo. Los agentes siempre deben tener en cuenta la visibilidad de los mensajes que reciben y usarla para informar sobre la generación de respuestas, la visibilidad de la respuesta y si se debe realizar un seguimiento de la solicitud original como parte del contexto de la conversación.
Al diseñar interacciones de agente para conversaciones de grupo, la elección entre mensajes públicos y dirigidos en diferentes situaciones requiere un juicio cuidadoso:
- Una solicitud dirigida a un agente debe dar lugar a una respuesta dirigida a menos que el usuario o la situación llamen explícitamente a una respuesta pública.
- Los mensajes públicos deben usarse en situaciones puramente informativas y no requieren contexto específico del usuario. Deben beneficiar a todo el grupo y no deben contener información privada.
- Tenga cuidado al usar tarjetas adaptables en mensajes de destino. Aunque el mensaje en sí está dirigido, las interacciones con una tarjeta todavía pueden generar actividad pública que los usuarios podrían no esperar.
- Use Prompt Preview cada vez que un agente responda a una solicitud de usuario de destino. En comparación con las respuestas entre comillas, esto ayuda a los usuarios a comprender la relación entre su mensaje original y la respuesta del agente sin necesidad de que busquen el mensaje anterior.
Controlar los errores
Asegúrese de controlar estos errores correctamente en el agente o la aplicación.
Esta es una lista de códigos de error, descripciones de errores y acciones de desarrollador para el SDK de Teams:
| Código de estado | Código de error | Descripción | Acción del desarrollador |
|---|---|---|---|
| 400 | Bad argument |
Al crear, la carga no es válida porque falta el destinatario. | Llame a WithRecipient(account, isTargeted: true) con un objeto Account válido. |
| 400 | Bad argument |
Los datos de destinatario se incluyeron en una operación de actualización o eliminación, donde no se permiten. | No pase a un destinatario al actualizar o eliminar. |
| 400 | INVALID_TARGETED_MESSAGE_ID |
En escenarios de la versión preliminar del mensaje, el identificador de mensaje de destino no es válido. | En el escenario de la vista previa del mensaje, compruebe que el identificador del mensaje de destino es correcto. |
| 403 | BotNotInConversationRoster |
La aplicación de agente o bot no es miembro de la conversación. | Asegúrese de que el bot está instalado en la conversación antes de enviar mensajes de destino. |
| 404 | ActivityNotFoundInConversation |
No se encontró el identificador del mensaje. Es posible que el mensaje se haya eliminado o expirado después de 24 horas. | Asegúrese de que el agente envía un nuevo mensaje de destino o espera la entrada del usuario, según la lógica de negocios. |
| 404 | TARGETED_MESSAGE_EXPIRED_OR_DELETED |
En escenarios de la versión preliminar del aviso, el mensaje al que se hace referencia se eliminó o expiró después de 24 horas. | Envíe un nuevo mensaje de destino o espere la entrada del usuario, en función de la lógica de negocios. |
Puede encontrar más detalles sobre otros códigos de error de mensajería aquí.
Ejemplo de código
| Ejemplo de nombre | Descripción | .NET | TypeScript | Python |
|---|---|---|---|---|
| Mensajes de destino del agente | En este ejemplo se muestra cómo usar la mensajería de destino en Microsoft Teams. Los mensajes de destino son mensajes privados que aparecen en un canal o chat de grupo, pero solo son visibles para un usuario específico. El ejemplo implementa un agente de recordatorio donde todas las respuestas del agente (confirmaciones, entregas de recordatorios, listas de recordatorios activas y confirmaciones de posposición) se envían como mensajes de destino. | View | View | View |
Contenido relacionado
Colaborar con nosotros en GitHub
El origen de este contenido se puede encontrar en GitHub, donde también puede crear y revisar problemas y solicitudes de incorporación de cambios. Para más información, consulte nuestra guía para colaboradores.