Conversaciones de chat de canal y grupo para agentes

Para permitir que los usuarios instalen un agente en un chat de grupo o equipo, agregue el teams ámbito o groupchat . Esto permite que todos los miembros de la conversación interactúen con el agente. Una vez instalado el agente, tiene acceso a metadatos sobre la conversación, como la lista de miembros de la conversación. Además, cuando se instala en un equipo, el agente tiene acceso a los detalles sobre ese equipo y a la lista completa de canales.

De forma predeterminada, los agentes de los chats y canales de grupo solo reciben mensajes cuando son directamente @mentioned. No reciben otros mensajes enviados a la conversación. Por ejemplo, el agente no recibe un mensaje cuando se menciona el equipo o el canal, o cuando alguien responde a un mensaje del agente sin @mentioning él. El SDK de Teams proporciona una ruta de actividad dedicada mention para controlar @mention eventos.

Directrices de diseño

En los chats y canales de grupo, diseñe el agente para conversaciones colaborativas con un valor claro, respuestas concisas y ruido mínimo.

Conversaciones en subprocesos

app.OnMessage(async (context, cancellationToken) =>
{
    // Send in the same thread, no quote
    await context.Send("Acknowledged", cancellationToken);

    // Send in the same thread with a visual quote of the inbound message
    await context.Reply("Got it!", cancellationToken);
});

app.on('message', async ({ send, reply }) => {
  // Send in the same thread, no quote
  await send('Acknowledged');

  // Send in the same thread with a visual quote of the inbound message
  await reply('Got it!');
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Send in the same thread, no quote
    await ctx.send("Acknowledged")

    # Send in the same thread with a visual quote of the inbound message
    await ctx.reply("Got it!")

Para enviar mensajes a un subproceso de forma proactiva, consulte Mensajes proactivos.

Enviar un mensaje durante la instalación

Cuando el agente se agrega por primera vez a un grupo o equipo, puede enviar un mensaje de introducción mediante la ruta del install.add ciclo de vida. Para obtener más información, consulte Mensajería proactiva.

Si envía un mensaje de introducción, incluya una breve descripción de las características del agente y cómo usarlas.

También puede almacenar durante la instalación para habilitar la conversationIdmensajería proactiva más adelante.

En el código siguiente se muestra un ejemplo de envío de mensajes de bienvenida durante la instalación:

app.OnInstall(async context => 
{ 
    await context.Send("Hello! I'm your agent. Here's what I can do..."); 
}); 

app.on('install.add', async ({ send }) => 
{ 
    await send('Hello! I\'m your agent. Here\'s what I can do...'); 
}); 

@app.on_install_add 
async def handle_install_add(ctx: ActivityContext[InstalledActivity]): 
    await ctx.send("Hello! I'm your agent. Here's what I can do...") 

No envíe mensajes de bienvenida proactivos a los usuarios individualmente cuando el agente esté instalado en un equipo o chat de grupo. Si envía un mensaje de bienvenida, postelo en la conversación instalada y mencione a la persona que agregó el agente.

No envíe un mensaje en los siguientes casos:

• Cuando el equipo es grande, por ejemplo, más de 100 miembros. Su agente puede ser visto como spam y la persona que lo agregó puede recibir quejas. Debe comunicar claramente la propuesta de valor del agente a todos los usuarios que ven el mensaje de bienvenida.
• El agente se menciona primero en un grupo o canal en lugar de agregarse primero a un equipo.
• Se cambia el nombre del grupo o canal.
• Un miembro del equipo se agrega a un grupo o canal.

Trabajar con menciones

En los chats y canales de grupo, los mensajes que @mention el agente incluye incluyen una entidad de mención en el texto del mensaje. Si el agente está configurado para recibir todos los mensajes, como con RSC, es posible que algunos mensajes entrantes no incluyan .@mention El agente puede recuperar otros usuarios mencionados en un mensaje y agregar menciones a los mensajes que envía. Los agentes de los chats de grupo habilitan las menciones de usuario mediante @mention; sin embargo, no admiten @everyone menciones.

Para los mensajes que incluyen @mentions, el texto del mensaje contiene marcado de mención como <at>@agentname</at>.

Recuperar menciones

Las menciones se devuelven en el entities objeto de la carga de actividad y contienen tanto el identificador único del usuario como el nombre del usuario mencionado. El texto del mensaje también incluye la mención, como <at>@John Smith<at>. Sin embargo, no confíe en el texto del mensaje para recuperar información sobre el usuario. Es posible que la persona que envía el mensaje lo altere. Por lo tanto, use el objeto entities.

Puede recuperar todas las menciones del mensaje filtrando la entities matriz de la actividad para las entradas con type establecido mentionen .

En el siguiente código se muestra un ejemplo de recuperación de menciones:

app.OnMessage(async context =>
{
    var mentions = context.Activity.Entities?
        .Where(e => e.Type == "mention")
        .ToList();

    if (mentions != null && mentions.Any())
    {
        var firstMention = mentions[0].Properties["mentioned"]?["name"]?.ToString();
        await context.Send($"Hello {firstMention}");
    }
    else
    {
        await context.Send("Aw, no one was mentioned.");
    }
});

app.on('message', async ({ activity, send }) => {
    const mentions = activity.entities?.filter(e => e.type === 'mention');

    if (mentions && mentions.length > 0) {
        const firstMention = mentions[0].mentioned;
        await send(`Hello ${firstMention.name}.`);
    } else {
        await send('Aw, no one was mentioned.');
    }
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    mentions = [e for e in (ctx.activity.entities or []) if e.type == "mention"]

    if mentions:
        first_mention = mentions[0].mentioned
        await ctx.send(f"Hello {first_mention.name}")
    else:
        await ctx.send("Aw, no one was mentioned.")

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Buscar y quitar @mention

En canales y chats de grupo, los usuarios suelen dirigirse a un agente o aplicación con un @mention. Antes de interpretar el mensaje, compruebe que la mención tenga como destino el agente o la aplicación y, a continuación, quite el texto de mención y recorte el espacio en blanco. Esto solo deja el comando o el símbolo del sistema del usuario para su procesamiento.

Quitar la mención impide que el nombre del agente o la aplicación interfiera con la coincidencia de comandos, el reconocimiento de intenciones, la búsqueda o el procesamiento de lenguaje natural. También permite que el mismo controlador procese mensajes de forma coherente en chats personales, chats de grupo y canales. Conserve otras menciones cuando formen parte de la solicitud del usuario.

string StripMentions(MessageActivity msg)
{
    var text = msg.Text ?? "";
    if (msg.Entities == null) return text;

    foreach (var entity in msg.Entities)
    {
        if (entity is MentionEntity mention && mention.Text != null)
        {
            text = text.Replace(mention.Text, "");
        }
    }

    return text.Trim();
}

app.on('message', async ({ activity, send }) => {
  const clean = activity.stripMentionsText().text;
  await send(`You said: ${clean}`);
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    clean = ctx.activity.strip_mentions_text().text
    await ctx.send(f"You said: {clean}")

Agregar menciones a los mensajes

El agente puede mencionar a otros usuarios en mensajes publicados en canales. Para incluir una mención insertada en el mensaje, coloque la mención en el texto del mensaje y agregue los detalles de mención a la matriz de entidades. El text campo de la entidad mention debe coincidir con el texto exacto del cuerpo del mensaje.

En el siguiente código se muestra un ejemplo de adición de menciones en los mensajes:

app.OnMessage(async context =>
{
    var user = context.Activity.From;
    var message = new MessageActivity($"Hello <at>{user.Name}</at>!").AddMention(user);
    await context.Send(message);
});

app.on('message', async ({ send, activity }) => {
    const user = activity.from;
    const message = new MessageActivity(`Hello <at>${user.name}</at>!`).addMention(user);
    await send(message);
});

@app.on_message 
async def handle_message(ctx: ActivityContext[MessageActivity]): 
    await ctx.send(MessageActivityInput(text="Hello!").add_mention(account=ctx.activity.from_))

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

También puede mencionar a los usuarios por su Microsoft Entra id. de objeto o nombre principal de usuario (UPN) y mencionar etiquetas en los mensajes del canal.

Compatibilidad con Microsoft Entra id. de objeto y UPN en la mención del usuario

Los bots pueden mencionar a los usuarios por Microsoft Entra id. de objeto o nombre principal de usuario (UPN), además de los identificadores de usuario. Los webhooks entrantes también admiten menciones de usuario en tarjetas adaptables con estos tipos de identificador.

El siguiente fragmento de código muestra un ejemplo de cómo mencionar a los usuarios con Entra id. de objeto y UPN mediante el SDK de Teams:

app.OnMessage(async context =>
{
    // Mention a user by their User Principal Name (UPN)
    var user = new Account { Id = "Adele@microsoft.com", Name = "Adele" };
    await context.Send(new MessageActivity("Hello!").AddMention(user));
});

app.on('message', async ({ send }) => {
    // Mention a user by their User Principal Name (UPN)
    const user = { id: 'Adele@microsoft.com', name: 'Adele' };
    await send(new MessageActivity('Hello!').addMention(user));
});

from microsoft_teams.api import Account, MessageActivityInput

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Mention a user by their User Principal Name (UPN)
    user = Account(id="Adele@microsoft.com", name="Adele")
    await ctx.send(MessageActivityInput(text="Hello!").add_mention(account=user))

{
    "type": "mention",
    "text": "<at>Adele</at>",
    "mentioned": {
            "id": "Adele@microsoft.com",
            "name": "Adele"
    }
}

Mención de etiquetas

El agente puede mencionar etiquetas en mensajes de texto y tarjetas adaptables publicadas en canales. Cuando el agente @mentions usa la etiqueta en un canal, la etiqueta se resalta y se notifica a las personas asociadas a la etiqueta. Cuando un usuario mantiene el puntero sobre la etiqueta, aparece un elemento emergente con los detalles de la etiqueta.

Mención de etiquetas en un mensaje de texto

Para mencionar una etiqueta, incluya una entidad de mención con "type": "tag" en el mensaje. El id campo debe ser el identificador de etiqueta codificado en base64 de la API List teamworkTags .

app.OnMessage(async context =>
{
    // Mention a tag using the tag's Graph API ID
    var tag = new Account { Id = "<base64-encoded-tag-id>", Name = "Test Tag" };
    await context.Send(new MessageActivity("Hello!").AddMention(tag));
});

app.on('message', async ({ send }) => {
    // Mention a tag using the tag's Graph API ID
    const tag = { id: '<base64-encoded-tag-id>', name: 'Test Tag' };
    await send(new MessageActivity('Hello!').addMention(tag));
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Mention a tag using the tag's Graph API ID
    tag = Account(id="<base64-encoded-tag-id>", name="Test Tag")
    await ctx.send(MessageActivityInput(text="Hello!").add_mention(account=tag))

Mencionar etiquetas en una tarjeta adaptable

En el esquema de tarjeta adaptable, en el mentioned objeto , agregue la "type": "tag" propiedad . Si no se agrega la "type": "tag" propiedad , el agente trata la mención como una mención del usuario.

Puede obtener la lista de las etiquetas disponibles en el canal mediante list teamworkTags API.

Ejemplo:

{
    "type": "mention",
    "text": "<at>Test Tag</at>",
    "mentioned": {
            "id": "base64 encoded id",
            "name": "Test Tag",
            "type": "tag"
    }
}

Parámetros de consulta

Código de error

Superado la limitación

Cualquier solicitud se puede evaluar con varios límites, según el ámbito, el tipo de ventana (corto y largo), el número de etiquetas por mensaje y otros factores. El primer límite alcanzado activa la limitación de solicitudes.

Asegúrese de que no supera los límites de limitación para evitar la entrega de mensajes con errores. Por ejemplo, un agente solo puede enviar dos mensajes con mención de etiquetas en una ventana de cinco segundos y cada mensaje solo puede tener hasta 10 etiquetas.

En la tabla siguiente se enumeran los límites de limitación de las menciones de etiquetas en un agente:

Limitaciones

• Las menciones de etiquetas solo se admiten en el flujo de mensajes de agente a cliente con texto y tarjeta adaptable.
• Las menciones de etiquetas no se admiten en canales compartidos y privados.
• Las menciones de etiquetas no se admiten en los conectores.
• Las menciones de etiquetas no admiten el flujo de invocación en un agente.

Paso siguiente

Consulte también

• SDK de Teams: cliente de API
• SDK de Teams: integración de Microsoft Graph
• Envío y recepción de mensajes de destino en conversaciones grupales
• Exposición de comandos de barra diagonal desde agentes y aplicaciones
• Creación de un canal privado en nombre del usuario
• SDK de Teams: Introducción a la integración de Teams