Envío y recepción de mensajes

Los agentes conversacionales se comunican con los usuarios a través de mensajería, lo que permite interacciones sin problemas. Puede simular conversaciones de la vida real con los usuarios a través de interacciones de texto o voz. Debe asegurarse de que las conversaciones del agente sean interactivas, dinámicas, adaptables y fáciles de usar.

Contenido del mensaje

La interacción de mensajes entre el agente y el usuario puede incluir diferentes tipos de contenido de mensaje que:

Uso de mensajes de texto enriquecido y emojis

El agente de Teams puede enviar texto enriquecido y emojis. Teams admite emojis a través de UTF-16, como U+1F600 para una cara sonriente.

Uso de mensajes de imagen

Para que aparezcan los mensajes del agente, el usuario puede agregar imágenes como datos adjuntos:

• Las imágenes pueden tener hasta 1024 × 1024 píxeles y 1 MB en formato PNG, JPEG o GIF. No se admiten gifs animados.

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

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

Para obtener más información sobre los datos adjuntos, vea Agregar datos adjuntos multimedia a los mensajes.

Uso de tarjetas adaptables

Un agente 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. Puede crear tarjetas adaptables en un agente y mostrarlas en varias aplicaciones, como Teams, su sitio web, etc.

Para más información, vea:

• Tarjetas adaptables.
• Referencia de tarjetas de Teams para las tarjetas admitidas.

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 Adaptive Card example with a Textbox",
            "type": "TextBlock",
            "weight": "bolder",
            "wrap": true
        },
        ],
        "spacing": "extraLarge",
        "type": "Container",
        "verticalContentAlignment": "center"
    }
    ]
}

Envío y recepción de mensajes

Enviar y recibir mensajes es la funcionalidad principal de un agente.

En un chat, cada mensaje es un Activity objeto de tipo messageType: message. Cuando alguien envía un mensaje, Microsoft Teams lo publica en el agente. Teams envía un objeto JSON al punto de conexión de mensajería del agente y solo permite un punto de conexión para la mensajería. A continuación, el agente comprueba el mensaje para averiguar su tipo y responde en consecuencia.

Las conversaciones básicas se administran a través del conector de Teams SDK Framework, que es una única API REST. Esta API permite al agente comunicarse con Teams y otros canales. El SDK de Bot Builder ofrece las siguientes características:

• Fácil acceso al conector del marco del SDK de Teams.
• Herramientas para administrar el flujo y el estado de la conversación.
• Formas sencillas de agregar Cognitive Services, como el procesamiento de lenguaje natural (NLP).

El agente obtiene mensajes de Teams mediante la Text propiedad y puede devolver una o varias respuestas a los usuarios.

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

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

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 actividad del agente, use el objeto de contexto turn Activity para leer una única solicitud de mensaje.

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

app.OnMessage(async context =>
{
    await context.Send($"Echo: {context.Activity.Text}");
});

app.on('message', async ({ activity, send }) => {
    await send(`Echo: '${activity.text}'`);
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    await ctx.send(f"Echo: {ctx.activity.text}")

{
    "type": "message",
    "id": "1485983408511",
    "timestamp": "2017-02-01T21:10:07.437Z",
    "localTimestamp": "2017-02-01T14:10:07.437-07:00",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "channelId": "msteams",
    "from": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB39ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen",
        "aadObjectId": "7faf8ab2-3d56-4244-b585-20c8a42ed2b8"
    },
    "conversation": {
        "conversationType": "personal",
        "id": "a:17I0kl9EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-"
    },
    "recipient": {
        "id": "28:c9e8c047-2a74-40a2-b28a-b162d5f5327c",
        "name": "Teams TestAgent"
    },
    "textFormat": "plain",
    "text": "Hello Teams TestAgent.Sending bold-italic rich text",
    "attachments": [
      {
            "contentType": "text/html",
            "content": "<div><div>Hello Teams TestAgent. Sending <strong>bold</strong>-<em>italic</em> rich text.</div>\n</div>"
      } 
    ],
    "entities": [
      { 
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo"
      }
    ],
    "channelData": {
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "locale": "en-US"
}

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 agente para que reciba eventos de recepción de lectura mediante la opción Leer recibos . El evento de recepción de lectura ayuda a mejorar la experiencia del usuario de las siguientes maneras:

• Puede configurar el agente 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 agente.

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

• Agregue el permiso RSCChatMessageReadReceipt.Read.Chat en el manifiesto de la aplicación, como se indica a continuación:

  • Manifiesto de aplicación v1.12 o posterior
  • Manifiesto de aplicación v1.11 o anterior

  
  "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 OnReadReceipt con context.Activity.Value.LastReadMessageId.

  El context.Activity.Value.LastReadMessageIdmétodo 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 OnReadReceipt método para recibir recibos de lectura con context.Activity.Value.LastReadMessageId el método :

  app.OnReadReceipt(async context =>
  
  {
      var lastReadMessageId = context.Activity.Value.LastReadMessageId;
      await context.Send("User read the agent's message");
  });
  

En el ejemplo siguiente se muestra una solicitud de evento de recibos de lectura que recibe un agente:

    {
        "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 Agent"
        },
        "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 o el usuario deben habilitar o deshabilitar la configuración de recibo de lectura.

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

Recepción de la actividad de edición de mensajes

Al editar un mensaje, el agente 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 agente, puede invalidar el OnMessageEdit controlador.

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

app.OnMessageEdit(async context =>
{
    await context.Send("message is updated");
}); 

app.on('messageEdit', async ({ activity, send }) => {
    const editedMessage = activity.text;
    await send(`The edited message is ${editedMessage}`);
});

{
"type":"messageUpdate",
"timestamp":"2022-10-28T17:19:39.4615413Z",
"localTimestamp":"2022-10-28T10:19:39.4615413-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_PM4mubmQZsYPx7jDyLeLf_YVA9sVPV08KMAFMjJWB_EUGveb9EVDh9TslNp9qjnzEBy3kgw01Jf1Kg",
    "name":"Mike Wilber",
    "aadObjectId":"520e4d1e-2108-43ee-a092-46a9507c6200"caching
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1pweuGJ44RkB90tiJNQ_I6g3vyuP4CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqRPB"
},
"recipient":{
    "id":"28:0d569679-gb4j-479a-b0d8-238b6e6b1149",
    "name":"TestAgent"
},
"entities":[
    {
        "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"editMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}  

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

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

Enviar un mensaje

Para enviar un mensaje de texto, especifique la cadena que desea enviar como actividad. En el controlador de actividad del agente, use el método del objeto de contexto turn context.Send(...) para enviar una única respuesta de mensaje. Use el método del multiple context.Send(...) calls 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:

app.OnMembersAdded(async context =>
{
    foreach (var member in context.Activity.MembersAdded)
    {
        if (member.Id != context.Activity.Recipient.Id)
        {
            await context.Send("Hello and welcome!");
        }
    }
});

   app.on('membersAdded', async ({ activity, send }) => {
    for (const member of activity.membersAdded ?? []) {
        if (member.id !== activity.recipient.id) {
            await send(`Welcome to the team ${member.name}`);
        }
    }
});

@app.on_members_added
async def handle_members_added(ctx: ActivityContext):
    for member in ctx.activity.members_added:
        if member.id != ctx.activity.recipient.id:
            await ctx.send(f"Welcome your new team member {member.id}")

{
    "type": "message",
    "from": {
        "id": "28:c9e8c047-2a34-40a1-b28a-b162d5f5327c",
        "name": "Teams TestAgent"
    },
    "conversation": {
        "id": "a:17I0kl8EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-",
        "name": "Convo1"
   },
   "recipient": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB25ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen"
    },
    "text": "My agent's reply",
    "replyToId": "1632474074231"
}

HTTP Request: {Service URL of your agent}/v3/conversations/{conversationId}/activities

{
    "type": "message",
    "from": {
        "id": "28:c9e8c047-2a34-40a1-b28a-b162d5f5327c",
        "name": "Teams TestAgent"
    },
    "conversation": {
        "id":"a:17I0kl8EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-",
        "name": "Convo1"
    },
    "recipient": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB25ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen"
    },
    "text": "My agent's reply"
}

Los mensajes enviados entre usuarios y agentes incluyen datos de canal internos dentro del mensaje. Estos datos permiten al agente comunicarse correctamente en ese canal. El SDK de Bot Builder permite modificar la estructura del mensaje.

Recepción de la actividad de recuperación de mensajes

Al recuperar un mensaje, el agente 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 agente, puede invalidar el OnMessageUndelete controlador.

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

app.OnMessageUndelete(async context =>
{
    await context.Send("message is undeleted");
});

app.on('messageUndelete', async ({ activity, send }) => {
    const undeletedMessage = activity.text;
    await send(`Previously the message was deleted. After undeleting, the message is now: "${undeletedMessage}"`);
});

{
"type":"messageUpdate",
"timestamp":"2022-10-28T17:19:39.4615413Z",
"localTimestamp":"2022-10-28T10:19:39.4615413-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_TM4mubmQZsYEo7jDyLeLf_YVA9sVPVO7KMAFMjJWB_EUGveb9EVDh9LgoNp9qjnzEBy4kgw83Jf1Kg",
    "name":"Alex Wilber",
    "aadObjectId":"976e4d1e-2108-43ee-a092-46a9507c5606"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1tewuGJ44RkB90tiJNQ_I4q8vyuN5CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqXQL"
},
"recipient":{
    "id":"28:0d469698-ab9d-479a-b0d8-758b6e6b1234",
    "name":"Testbot"
},
"entities":[
    {
           "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"undeleteMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}  

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

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

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

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

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

En el ejemplo siguiente se muestra una notificación de actividad de mensaje de eliminación temporal mediante OnMessageSoftDelete cuando se elimina temporalmente un mensaje:

app.OnMessageSoftDelete(async context =>
{
    await context.Send("message is soft deleted");
}); 

app.on('messageSoftDelete', async ({ activity, send }) => {
    const messageId = activity.id;
    await send(`The deleted message id is ${messageId}`);
});

{
"type":"messageDelete",
"timestamp":"2022-10-28T17:19:43.1612052Z",
"localTimestamp":"2022-10-28T10:19:43.1612052-07:00",
"id":"1666977568748",
"channelId":"msteams",
"serviceUrl":"https://canary.botapi.skype.com/amer/",
"from": {
    "id":"29:1BLjP9j3_TM4mubmQZsYEo7jDyLeLf_YVA9sVPVO7KMAFMjJWB_EUGveb9EVDh9LgoNp9qjnzEBy4kgw83Jf1Kg",
    "name":"Alex Wilber",
    "aadObjectId":"976e4d1e-2108-43ee-a092-46a9507c5606"
},
"conversation":{
    "conversationType":"personal",
    "tenantId":"528dbe3f-15e0-4e37-84a1-00cc305847dd","id":"a:1tewuGJ44RkB90tiJNQ_I4q8vyuN5CYA_f-v6f0Vd-Bs3Ce85C73Ah1y8TvyjESsTHWjjgw-gnsuIuCUOWkfOCq6qaUYsk2_-fj93XXXHUMAUzhFFvTnaCU7V4WiMqXQL"
},
"recipient":{
    "id":"28:0d469698-ab9d-479a-b0d8-758b6e6b1235",
    "name":"Testagent"
},
"entities":[
    {
        "locale":"en-US",
        "country":"US",
        "platform":"Web",
        "timezone":"America/Los_Angeles",
        "type":"clientInfo"
    }
],
"channelData":{
    "eventType":"softDeleteMessage",
    "tenant":{"id":"528dbe3f-15e0-4e37-84a1-00cc305847dd"}
},
"locale":"en-US",
"localTimezone":"America/Los_Angeles"
}  

Actualización y eliminación de mensajes enviados desde el agente

El agente puede actualizar dinámicamente los mensajes después de enviarlos en lugar de tenerlos como instantáneas estáticas de datos. Los mensajes también se pueden eliminar mediante el método del marco del SDK de context.Api.Conversations.Activities.DeleteAsync(...) Teams.

Actualizar mensajes

Puede usar actualizaciones de mensajes dinámicos para escenarios como las actualizaciones de sondeo, la modificación de las acciones disponibles después de presionar un botón o cualquier otro cambio de estado asincrónico.

No es necesario que el nuevo mensaje coincida con el tipo original. Por ejemplo, si el mensaje original contenía datos adjuntos, el nuevo mensaje puede ser un mensaje de texto simple.

app.OnMessage(async context =>
{
    // Send initial message
    var response = await context.Send("Your Message");
    var conversationId = context.Activity.Conversation.Id;
    var activityId = response.Id;

    var updatedActivity = new MessageActivity("The new text for the activity");

    await context.Api.Conversations.Activities.UpdateAsync(conversationId, activityId, updatedActivity);
});

app.on('message', async ({ activity, api, send }) => {
    // Send initial message
    const response = await send('Your Message');
    const conversationId = activity.conversation.id;
    const activityId = response.id;

    await api.conversations.activities(conversationId).update(activityId, {
        type: 'message',
        text: 'The new text for the activity'
    });
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Send initial message
    response = await ctx.send("Your Message")
    conversation_id = ctx.activity.conversation.id
    activity_id = response.id

    await ctx.api.conversations.activities(conversation_id).update(
        activity_id, MessageActivityInput(text="The new text for the activity")
    )

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 identificador de actividad devuelto por la llamada post original.

PUT /v3/conversations/{conversationId}/activities/{activityId}

Ahora que ha actualizado los mensajes, actualice la tarjeta existente en la selección de botón para las actividades entrantes.

Actualizar tarjetas

Para actualizar la tarjeta existente en la selección de botón, puede usar ReplyToId de actividad entrante.

app.OnMessage(async context =>
{
    var conversationId = context.Activity.Conversation.Id;
    var activityId = context.Activity.ReplyToId;

    var updatedActivity = new MessageActivity();
    updatedActivity.Attachments.Add(card.ToAttachment());

    await context.Api.Conversations.Activities.UpdateAsync(conversationId, activityId, updatedActivity);
});

app.on('message', async ({ activity, api }) => {
    const conversationId = activity.conversation.id;
    const activityId = activity.replyToId;

    await api.conversations.activities(conversationId).update(activityId, {
        type: 'message',
        attachments: [card]
    });
});

@app.on_message
async def handle_update_card(ctx: ActivityContext[MessageActivity]):
    conversation_id = ctx.activity.conversation.id
    activity_id = ctx.activity.reply_to_id

    await ctx.api.conversations.activities(conversation_id).update(
        activity_id, MessageActivityInput().add_card(card)
    )

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 identificador de actividad devuelto por la llamada post original.

PUT /v3/conversations/{conversationId}/activities/{activityId}

Ahora que ha actualizado las tarjetas, puede eliminar mensajes mediante el marco del SDK de Teams.

Eliminar mensajes

En El marco del SDK de Teams, cada mensaje tiene su identificador de actividad único. Los mensajes se pueden eliminar mediante el método del marco del SDK de context.Api.Conversations.Activities.DeleteAsync(...) Teams.

app.OnMessage(async context =>
{
    var conversationId = context.Activity.Conversation.Id;

    foreach (var activityId in _list)
    {
        await context.Api.Conversations.Activities.DeleteAsync(conversationId, activityId);
    }
});

app.on('message', async ({ activity, api }) => {
    const conversationId = activity.conversation.id;

    for (const activityId of activityIds) {
        await api.conversations.activities(conversationId).delete(activityId);
    }
});

@app.on_message
async def handle_delete(ctx: ActivityContext[MessageActivity]):
    conversation_id = ctx.activity.conversation.id

    for activity_id in _list:
        await ctx.api.conversations.activities(conversation_id).delete(activity_id)

Para eliminar una actividad existente en una conversación, incluya el conversationId y activityId en el punto de conexión de la solicitud.

DELETE /v3/conversations/{conversationId}/activities/{activityId}

Respuestas entre comillas

Las respuestas entre comillas permiten al agente hacer referencia a un mensaje anterior en la conversación. Cuando un usuario envía un mensaje que cita otro mensaje, el agente recibe metadatos estructurados sobre el contenido entre comillas. El agente también puede enviar mensajes que citan mensajes anteriores.

Recibir respuestas citadas

app.OnMessage(async context =>
{
    var quotes = context.Activity.GetQuotedMessages();

    if (quotes.Count > 0)
    {
        var quote = quotes[0].QuotedReply;
        await context.Reply(
            $"You quoted message {quote.MessageId} from {quote.SenderName}: \"{quote.Preview}\"");
    }
});

app.on('message', async ({ activity, reply }) => {
  const quotes = activity.getQuotedMessages();

  if (quotes.length > 0) {
    const quote = quotes[0].quotedReply;
    await reply(
      `You quoted message ${quote.messageId} from ${quote.senderName}: "${quote.preview}"`
    );
  }
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    quotes = ctx.activity.get_quoted_messages()

    if quotes:
        quote = quotes[0].quoted_reply
        await ctx.reply(
            f"You quoted message {quote.message_id} from {quote.sender_name}: \"{quote.preview}\""
        )

Enviar respuestas entre comillas

app.OnMessage(async context =>
{
    // Reply() automatically quotes the inbound message
    await context.Reply("Got it!");
});

app.OnMessage(async context =>
{
    // Quote a specific message by its ID
    var parentMessageId = "1772050244572";
    await context.Quote(parentMessageId, "Referencing an earlier message");
});

app.on('message', async ({ reply }) => {
  // reply() automatically quotes the inbound message
  await reply('Got it!');
});

app.on('message', async ({ quote }) => {
  // Quote a specific message by its ID
  const parentMessageId = '1772050244572';
  await quote(parentMessageId, 'Referencing an earlier message');
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # reply() automatically quotes the inbound message
    await ctx.reply("Got it!")

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Quote a specific message by its ID
    parent_message_id = "1772050244572"
    await ctx.quote(parent_message_id, "Referencing an earlier message")

Compilación de respuestas entre comillas para enviar mensajes de forma proactiva

var parentMessageId = "1772050244572";
var firstMessageId = "1772050244573";
var secondMessageId = "1772050244574";

// Single quote with response below it
var msg = new MessageActivity()
    .AddQuote(parentMessageId, "Here is my response");
await app.Send(conversationId, msg);

// Multiple quotes with interleaved responses
msg = new MessageActivity()
    .AddQuote(firstMessageId, "response to first")
    .AddQuote(secondMessageId, "response to second");
await app.Send(conversationId, msg);

// Grouped quotes — omit response to group quotes together
msg = new MessageActivity("see below for previous messages")
    .AddQuote(firstMessageId)
    .AddQuote(secondMessageId, "response to both");
await app.Send(conversationId, msg);

import { MessageActivity } from '@microsoft/teams.api';

const parentMessageId = '1772050244572';
const firstMessageId = '1772050244573';
const secondMessageId = '1772050244574';

// Single quote with response below it
let msg = new MessageActivity()
  .addQuote(parentMessageId, 'Here is my response');
await app.send(conversationId, msg);

// Multiple quotes with interleaved responses
msg = new MessageActivity()
  .addQuote(firstMessageId, 'response to first')
  .addQuote(secondMessageId, 'response to second');
await app.send(conversationId, msg);

// Grouped quotes — omit response to group quotes together
msg = new MessageActivity('see below for previous messages')
  .addQuote(firstMessageId)
  .addQuote(secondMessageId, 'response to both');
await app.send(conversationId, msg);

from microsoft_teams.api.activities.message import MessageActivityInput

parent_message_id = "1772050244572"
first_message_id = "1772050244573"
second_message_id = "1772050244574"

# Single quote with response below it
msg = (MessageActivityInput()
    .add_quote(parent_message_id, "Here is my response"))
await app.send(conversation_id, msg)

# Multiple quotes with interleaved responses
msg = (MessageActivityInput()
    .add_quote(first_message_id, "response to first")
    .add_quote(second_message_id, "response to second"))
await app.send(conversation_id, msg)

# Grouped quotes — omit response to group quotes together
msg = (MessageActivityInput(text="see below for previous messages")
    .add_quote(first_message_id)
    .add_quote(second_message_id, "response to both"))
await app.send(conversation_id, msg)

Envío de mensajes en los 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 App 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 agente contiene la siguiente información:

• eventType: el tipo de evento de Teams solo se pasa en los casos de eventos de conversación en el agente de Teams.
• 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: se pasa solo en contextos de canal, cuando se menciona el agente o para eventos en canales de teams, donde se agrega el agente.
  • 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: en desuso. Esta propiedad solo se incluye por compatibilidad con versiones anteriores.
• channelData.teamsChannelId: en desuso. Esta propiedad solo se incluye por compatibilidad con versiones anteriores.

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"
    }
}

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 App 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 agente 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 casos de (how-to/conversations/subscribe-to-conversation-events.md#team-renamed).
• channel: se pasa solo en contextos de canal, cuando se menciona el agente o para eventos en canales de teams, donde se agrega el agente.
  • 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: en desuso. Esta propiedad solo se incluye por compatibilidad con versiones anteriores.
• channelData.teamsChannelId: en desuso. 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"
    }
}

Códigos de estado de las API conversacionales del agente

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:

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 agente debe evitar reintentar los códigos de estado que no se especifican:

Encabezados de solicitud del agente

Las solicitudes salientes actuales al agente no contienen en el encabezado ni en la dirección URL ninguna información que ayude a los agentes a enrutar el tráfico sin desempaquetar toda la carga. Las actividades se envían al agente a través de una dirección URL similar a https://< your_domain>/api/messages. Se reciben solicitudes para mostrar el identificador de conversación y el identificador de inquilino en los encabezados.

Campos de encabezado de solicitud

Se agregan dos campos de encabezado de solicitud no estándar a todas las solicitudes enviadas a los agentes, tanto para el flujo asincrónico como para el flujo sincrónico. En la tabla siguiente se proporcionan los campos de encabezado de solicitud y sus valores:

Si el identificador de inquilino o conversación no está presente en la actividad o no se validó en el lado del servicio, el valor está vacío.

Recibir solo mensajes mencionados

Para permitir que los agentes obtengan solo los mensajes de canal o chat en los que está @mentionedel agente, debe filtrar los mensajes. Use el siguiente fragmento de código para permitir que el agente reciba solo los mensajes en los que es @mentioned:

  app.OnMessage(async context =>
{
    if (!context.Activity.GetMentions().Any(mention => mention.Mentioned.Id.Equals(context.Activity.Recipient.Id, StringComparison.OrdinalIgnoreCase)))
    {
        return;
    }

    await context.Send("Using RSC the agent can receive messages across channels or chats in team without being @mentioned.");
});

Si quiere que el agente reciba todos los mensajes, no es necesario filtrarlos @mention .

Paso siguiente

Canalizar y agrupar conversaciones de chat con un agente

Vea también

Eventos de conversación en el agente de Teams