Conversas de canal e chat em grupo para agentes

Para permitir que os usuários instalem um agente em um chat de equipe ou em grupo, adicione o teams escopo ou groupchat . Isso permite que todos os membros da conversa interajam com seu agente. Depois que o agente é instalado, ele tem acesso aos metadados sobre a conversa, como a lista de membros da conversa. Além disso, quando ele é instalado em uma equipe, o agente tem acesso aos detalhes sobre essa equipe e à lista completa de canais.

Por padrão, os agentes em chats e canais em grupo só recebem mensagens quando estão diretamente @mentioned. Eles não recebem outras mensagens enviadas para a conversa. Por exemplo, seu agente não recebe uma mensagem quando a equipe ou canal é mencionado, ou quando alguém responde a uma mensagem de seu agente sem @mentioning ele. O SDK do Teams fornece uma rota de atividade dedicada mention para lidar com @mention eventos.

Diretrizes de design

Em chats e canais em grupo, projete seu agente para conversas colaborativas com valor claro, respostas concisas e ruído mínimo.

Conversas encadeadas

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 mensagens para um thread proativamente, consulte Mensagens proativas.

Enviar uma mensagem na instalação

Quando seu agente é adicionado pela primeira vez a um grupo ou equipe, você pode enviar uma mensagem de apresentação usando a rota do install.add ciclo de vida. Para obter mais informações, consulte mensagens proativas.

Se você enviar uma mensagem de apresentação, inclua uma breve descrição dos recursos do agente e como usá-los.

Você também pode armazenar o durante a conversationId instalação para habilitar mensagens proativas posteriormente.

O código a seguir mostra um exemplo de envio de mensagens de boas-vindas na instalação:

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...") 

Não envie mensagens de boas-vindas proativas aos usuários individualmente quando o agente estiver instalado em uma equipe ou chat em grupo. Se você enviar uma mensagem de boas-vindas, poste-a na conversa instalada e mencione a pessoa que adicionou o agente.

Não envie uma mensagem nos seguintes casos:

• Quando a equipe é grande, por exemplo, maior que 100 membros. Seu agente pode ser visto como spam e a pessoa que o adicionou pode receber reclamações. Você deve comunicar claramente a proposta de valor do seu agente a todos que virem a mensagem de boas-vindas.
• Seu agente é mencionado pela primeira vez em um grupo ou canal, em vez de ser adicionado pela primeira vez a uma equipe.
• Um grupo ou canal é renomeado.
• Um membro da equipe é adicionado a um grupo ou canal.

Trabalhe com menções

Em chats e canais em grupo, mensagens informando que @mention seu agente inclui uma entidade de menção no texto da mensagem. Se o agente estiver configurado para receber todas as mensagens, como com RSC, algumas mensagens de entrada podem não incluir um @mention. Seu agente pode recuperar outros usuários mencionados em uma mensagem e adicionar menções às mensagens enviadas. Os agentes em chats em grupo permitem menções de usuário usando @mention; no entanto, eles não suportam @everyone menções.

Para mensagens que incluem @mentions, o texto da mensagem contém marcação de menção como <at>@agentname</at>.

Recupere menções

As menções são retornadas no entities objeto no conteúdo da atividade e contêm a ID exclusiva do usuário e o nome do usuário mencionado. O texto da mensagem também inclui a menção, como <at>@John Smith<at>. No entanto, não confie no texto da mensagem para recuperar qualquer informação sobre o usuário. É possível que a pessoa que envia a mensagem a altere. Portanto, use o objeto entities.

Você pode recuperar todas as menções na mensagem filtrando a entities matriz na atividade em busca de entradas com definido como mentiontype .

O código a seguir mostra um exemplo de recuperação de menções:

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

Verificar e remover @mention

Em canais e chats em grupo, os usuários geralmente se dirigem a um agente ou aplicativo com um @mention. Antes de interpretar a mensagem, Marque se a menção se destina ao seu agente ou aplicativo, remova o texto da menção e corte o espaço em branco. Isso deixa apenas o comando ou prompt do usuário para processamento.

A remoção da menção impede que o nome do agente ou do aplicativo interfira na correspondência de comandos, no reconhecimento de intenção, na pesquisa ou no processamento de linguagem natural. Ele também permite que o mesmo manipulador processe mensagens de forma consistente em chats pessoais, chats em grupo e canais. Preserve outras menções quando fizerem parte da solicitação do usuário.

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

Adicione menções às suas mensagens

Seu agente pode menção outros usuários em mensagens postadas em canais. Para incluir uma menção embutida na sua mensagem, coloque a menção no texto da mensagem e adicione os detalhes da menção à matriz de entidades. O text campo na entidade de menção deve corresponder ao texto exato no corpo da mensagem.

O código a seguir mostra um exemplo de como adicionar menções às suas mensagens:

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

Você também pode menção usuários por sua ID de Objeto do Microsoft Entra ou Nome Principal do Usuário (UPN) e marcas de menção em mensagens de canal.

Suporte para ID de Objeto e UPN do Microsoft Entra na menção do usuário

Os bots podem menção usuários por ID de Objeto ou Nome Principal do Usuário (UPN) do Microsoft Entra, além de IDs de usuário. Os Webhooks de entrada também dão suporte a menções de usuários em Cartões Adaptáveis usando esses tipos de ID.

O trecho de código a seguir mostra um exemplo de menção de usuários com ID de Objeto do Entra e UPN usando o SDK do 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"
    }
}

Marcar menção

Seu agente pode menção marcas em mensagens de texto e Cartões Adaptáveis postados em canais. Quando o agente @mentions usa a tag em um canal, a tag é destacada e as pessoas associadas à tag são notificadas. Quando um usuário passa o mouse sobre a tag, um pop-up é exibido com os detalhes da tag.

Mencionar marcas em uma mensagem de texto

Para menção uma marca, inclua uma entidade de menção na "type": "tag" sua mensagem. O id campo deve ser a ID da marca codificada em base64 da 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 marcas em um Cartão Adaptável

No esquema do Cartão Adaptável, no mentioned objeto, adicione a "type": "tag" propriedade. Se a "type": "tag" propriedade não for adicionada, o agente tratará a menção como uma menção do usuário.

Você pode obter a lista das marcas disponíveis no canal usando a API List teamworkTags .

Exemplo:

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

Parâmetros de Consulta

Código de erro

Redução dos limites

Qualquer solicitação pode ser avaliada em relação a vários limites, dependendo do escopo, do tipo de janela (curta e longa), do número de marcas por mensagem e de outros fatores. O primeiro limite a ser alcançado dispara o comportamento de limitação.

Certifique-se de não exceder os limites de limitação para evitar falha na entrega de mensagens. Por exemplo, um agente pode enviar apenas duas mensagens com menção de tag em uma janela de cinco segundos e cada mensagem pode ter apenas até 10 tags.

A tabela a seguir lista os limites de limitação para menções de marcas em um agente:

Limitações

• As menções de marcas têm suporte apenas no fluxo de mensagens do agente para o cliente com texto e Cartão Adaptável.
• Não há suporte para menções de marcação em canais compartilhados e privados.
• Não há suporte para menções de marcas em conectores.
• As menções de marca não dão suporte ao fluxo de invocação em um agente.

Próxima etapa

Confira também

• SDK do Teams - Cliente de API
• SDK do Teams - Integração com o Microsoft Graph
• Enviar e receber mensagens direcionadas em conversas em grupo
• Expor comandos de barra de agentes e aplicativos
• Criar canal privado em nome do usuário
• SDK do Teams - Visão geral da integração do Teams