Canais e conversas de chat em grupo com um bot do Microsoft Teams

Artigo
11/19/2024

Importante

Os exemplos de código nesta secção baseiam-se na versão 4.6 e versões posteriores do SDK do Bot Framework. Se estiver à procura de documentação para versões anteriores, veja a secção bots – SDK v3 na pasta SDKs Legados da documentação.

Para instalar o bot do Microsoft Teams em uma equipe ou chat em grupo, adicione o escopo teams ou groupchat ao seu bot. Isso permite que todos os membros da conversa interajam com o seu bot. Depois que o bot é instalado, ele tem acesso aos metadados sobre a conversa, como a lista de membros da conversa. Além disso, quando está instalado numa equipa, o bot tem acesso a detalhes sobre essa equipa e à lista completa de canais.

Os bots num grupo ou canal só recebem mensagens quando são mencionados @botname. Não recebem outras mensagens enviadas para a conversação. O bot deve ser @mentioned diretamente. O bot não recebe uma mensagem quando a equipa ou o canal é mencionado ou quando alguém responde a uma mensagem do seu bot sem @mentioning o mesmo.

Observação

O RSC para todas as mensagens de chat só está disponível na pré-visualização do programador público.
Com o consentimento específico do recurso (RSC), um bot pode receber todas as mensagens de canal nas equipas nas quais está instalado sem ser @mentioned. Para obter mais informações, confira receber todas as mensagens de canal com o RSC.
A publicação de uma mensagem ou cartão ajustável num canal privado não é suportada.

Veja o seguinte vídeo para saber mais sobre as conversações de chat de canal e grupo com um bot:

Diretrizes de design

Ao contrário do que ocorre em chats pessoais, seu bot deve fornecer uma introdução rápida em chats e canais em grupo. Você deve seguir essas e mais diretrizes de design de bot. Para obter mais informações sobre como projetar bots no Teams, confira como projetar conversas de bot em canais e chats.

Agora, você pode criar novas threads de conversa e gerenciar facilmente diferentes conversas nos canais.

Crie novas threads de conversa

Quando o bot é instalado em uma equipe, você deve criar uma nova thread de conversa em vez de responder a uma existente. Por vezes, é difícil diferenciar entre duas conversas. Se a conversação estiver por tópicos, é mais fácil organizar e gerir diferentes conversações em canais. Essa é uma forma de mensagens proativas.

Em seguida, recupere as menções usando o objeto entities e adicione menções às suas mensagens usando o objeto Mention.

Trabalhe com menções

Cada mensagem para o bot de um grupo ou canal contém um @mention com o respetivo nome no texto da mensagem. Seu bot também pode recuperar outros usuários mencionados em uma mensagem e adicionar menções a quaisquer mensagens que enviar. Os bots em conversas de grupo permitem menções de utilizadores com @mention; no entanto, não suportam @everyone menções.

Também tem de retirar o @mentions conteúdo da mensagem que o bot recebe.

Recupere menções

As menções são retornadas no objeto entities do conteúdo 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 dependa do texto na mensagem para obter informações sobre o utilizador. É possível que a pessoa que está a enviar a mensagem a altere. Portanto, use o objeto entities.

Você pode recuperar todas as menções na mensagem chamando a função GetMentions no SDK Bot Builder, que retorna uma matriz de objetos Mention.

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

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Resolves the mentions from the entities activity.
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

Referência do SDK

this.onMessage(async (turnContext, next) => {
    
    // Resolves the mentions from the entities activity.
    const mentions = TurnContext.getMentions(turnContext.activity);
    if (mentions){
        const firstMention = mentions[0].mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.sendActivity(`Hello ${firstMention.name}.`);
    } else {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.sendActivity(`Aw, no one was mentioned.`);
    }

    await next();
});

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

Referência do SDK

@staticmethod
// Resolves the mentions from the entities of this activity.
def get_mentions(activity: Activity) -> List[Mention]:
    result: List[Mention] = []
    if activity.entities is not None:
        for entity in activity.entities:
            if entity.type.lower() == "mention":
                    result.append(entity)
     return result

Adicione menções às suas mensagens

Existem dois tipos de menções:

Menção de utilizador
Etiquetar menção

Observação

A menção de utilizador e menção de etiquetas é suportada tanto para mensagens de texto como para Cartões Ajustáveis.

Menção de utilizador

O bot pode menção outros utilizadores em mensagens publicadas em canais.

O objeto Mention tem duas propriedades que você deve definir usando o seguinte:

Inclua @nome de usuário no texto da mensagem.
Inclua o objeto de menção na coleção de entidades.

O SDK do Bot Framework fornece métodos auxiliares e objetos para criar menções.

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

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var mention = new Mention
    {
        Mentioned = turnContext.Activity.From,
        Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
        Type = "mention",
    };

    // Returns a simple text message.
    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

this.onMessage(async (turnContext, next) => {
    const mention = {
        mentioned: turnContext.activity.from,
        text: `<at>${ new TextEncoder().encode(turnContext.activity.from.name) }</at>`,
        type: "mention",
    } as Mention;

    // Returns a simple text message.
    const replyActivity = MessageFactory.text(`Hello ${mention.text}`);
    replyActivity.entities = [mention];

    // Sends a message activity to the sender of the incoming activity.
    await turnContext.sendActivity(replyActivity);

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

O campo text no objeto da matriz entities deve corresponder a uma parte do campo text da mensagem. Se não, a menção é ignorada.

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

async def _mention_activity(self, turn_context: TurnContext):
        mention = Mention(
            mentioned=turn_context.activity.from_property,
            text=f"<at>{turn_context.activity.from_property.name}</at>",
            type="mention"
        )
        // Returns a simple text message.
        reply_activity = MessageFactory.text(f"Hello {mention.text}")
        # Sends a message activity to the sender of the incoming activity.
        reply_activity.entities = [Mention().deserialize(mention.serialize())]
        await turn_context.send_activity(reply_activity)

Agora você pode enviar uma mensagem de introdução quando o bot for instalado pela primeira vez ou adicionado a um grupo ou equipe.

Suporte para Microsoft Entra ID de Objeto e UPN no menção do utilizador

Os bots suportam IDs de menção de utilizador, como Microsoft Entra ID de Objeto e Nome do Principal de Utilizador (UPN), além dos IDs existentes. Os Webhooks recebidos começam a suportar menção de utilizador no Cartão Ajustável com o ID de Objeto Microsoft Entra e UPN.

O fragmento de código seguinte mostra um exemplo de menção de utilizadores com o ID do Objeto Entra e o UPN numa mensagem de texto:

var userId = "Adele@microsoft.com"; //User Principle Name
var mention = new ChannelAccount(userId, "Adele"); 
var mentionObj = new Mention 
{
    Mentioned = mention,
    Text = $"<at>{mention.Name}</at>" ,
    Type = "mention"
}; 

// Returns a simple text message.var replyActivity = MessageFactory.Text($"Hello {mentionObj.Text}.");replyActivity.Entities = new List<Entity> { mentionObj };

// Sends an activity to the sender of the incoming activity.await turnContext.SendActivityAsync(replyActivity, cancellationToken);

O fragmento de código seguinte mostra um exemplo de menção de utilizadores com o ID do Objeto Entra e o UPN num Cartão Ajustável:

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

Etiquetar menção

O bot pode menção etiquetas em mensagens sms e Cartões Ajustáveis publicados em canais. Quando o bot @mentions a etiqueta num canal é realçada e as pessoas associadas à etiqueta são notificadas. Quando um utilizador paira o cursor sobre a etiqueta, é apresentado um pop-up com os detalhes da etiqueta.

Mencionar etiquetas numa mensagem sms

mention.properties No objeto, adicione a propriedade 'type': 'tag'. Se a propriedade 'type': 'tag' não for adicionada, o bot trata a menção como um utilizador menção.

Exemplo:

O type:tag é adicionado como um Properties em ChannelAccount.

Referência do SDK

var mention = new ChannelAccount(tagId, "Test Tag"); 
mention.Properties = JObject.Parse("{'type': 'tag'}"); 
var mentionObj = new Mention 
{ 
    Mentioned = mention, 
    Text = "<at>Test Tag</at>" 
}; 

var replyActivity = MessageFactory.Text("Hello " + mentionObj.Text); 
replyActivity.Entities = new List<Microsoft.Bot.Schema.Entity> { mentionObj }; 
await turnContext.SendActivityAsync(replyActivity, cancellationToken);

Mencionar etiquetas num Cartão Ajustável

No esquema Cartão Ajustável, por baixo do mentioned objeto, adicione a "type": "tag" propriedade . Se a "type": "tag" propriedade não for adicionada, o bot trata o menção como um utilizador menção.

Pode obter a lista das etiquetas disponíveis no canal com a API List teamworkTags .

Exemplo:

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

Parâmetros de Consulta

Nome	Descrição
`type`	O tipo de menção. O tipo suportado é `tag`.
`id`	O identificador exclusivo da etiqueta. Para obter mais informações, veja teamworkTag.

Código de erro

Código de status	Código de erro	Valores de mensagens	Pedido de repetição	Ação de programador
400	Código: `Bad Request`	A etiqueta mencionada com o ID {id string} não existe na equipa atual A etiqueta só pode ser mencionada no canal Etiqueta mencionada inválida porque não existe nenhuma etiqueta na equipa	Não	Reavalie o payload do pedido para erros. Verifique a mensagem de erro devolvida para obter detalhes.
502	Código: `Bad Gateway`	ID de grupo de equipa inválido ID de inquilino com formato incorreto para a etiqueta O ID de Menção não pode ser resolvido	Não	Repita manualmente.

Redução dos limites

Qualquer pedido pode ser avaliado em relação a vários limites, consoante o âmbito, o tipo de janela (curto e longo), o número de etiquetas por mensagem e outros fatores. O primeiro limite a ser alcançado dispara o comportamento de limitação.

Certifique-se de que não excede os limites de limitação para evitar a entrega de mensagens falhadas. Por exemplo, um bot só pode enviar duas mensagens com etiquetas menção numa janela de cinco segundos e cada mensagem só pode ter até 10 etiquetas.

A tabela seguinte lista os limites de limitação para menções de etiquetas num bot:

Âmbito	Tipo de Janela	Número de etiquetas por mensagem	Janelas de tempo (seg.	Número máximo de mensagens por período de tempo
Por bot por thread	Abreviado	10	5	2
	Longo	10	60	5
Todos os bots por thread	Abreviado	10	5	4
	Longo	10	60	5

Limitações

As menções de etiquetas são suportadas apenas no fluxo de mensagens de bot para cliente com texto e Cartão Ajustável.
As menções de etiquetas não são suportadas em canais partilhados e privados.
As menções de etiquetas não são suportadas nos conectores.
As menções de etiquetas não suportam o fluxo de invocação num bot.

Enviar uma mensagem na instalação

Quando o bot é adicionado pela primeira vez ao grupo ou à equipe, uma mensagem de introdução deve ser enviada. A mensagem deve fornecer uma breve descrição dos recursos do bot e como usá-los. Você deve assinar o evento conversationUpdate com o eventType teamMemberAdded. O evento é enviado quando qualquer novo membro da equipe for adicionado. Verifique se o novo membro adicionado é o bot. Para obter mais informações, confira enviar uma mensagem de boas-vindas a um novo membro da equipe.

Pode enviar uma mensagem pessoal a cada membro da equipa quando o bot for adicionado. Para tal, obtenha a lista da equipa e envie uma mensagem direta a cada utilizador.

Observação

Certifique-se de que a mensagem enviada pelo bot é relevante e acrescenta valor à mensagem inicial e não envia spam aos utilizadores.

Não envie uma mensagem nos seguintes casos:

Por exemplo, quando a equipa é grande, tem mais de 100 membros. Seu bot pode ser visto como spam e a pessoa que o adicionou pode receber reclamações. Você deve comunicar claramente a proposta de valor do bot para todos que veem a mensagem de boas-vindas.
Seu bot é mencionado primeiro em um grupo ou canal em vez de ser adicionado primeiramente a uma equipe.
Um grupo ou canal é renomeado.
Um membro da equipe é adicionado a um grupo ou canal.

Exemplos de bot do Teams

Exemplo de código

Para obter exemplos de trabalho completos que demonstram a funcionalidade, veja os seguintes exemplos do Teams para o Bot Framework:

Nome de exemplo	Descrição	.NET	Node.js	Python	Manifesto
Bot de conversas do Teams	Este exemplo mostra como utilizar diferentes eventos de conversação de bot disponíveis no bot framework v4 para o âmbito pessoal e de equipas.	View	View	View	View
Autenticação com OAuthPrompt	Este exemplo mostra a autenticação e as mensagens básicas no Bot Framework v4.	View	View	View	View
Carregamento de ficheiros do Teams	Este exemplo mostra como utilizar ficheiros com um bot numa conversação um-para-um.	View	View	View	View
Caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x)	Este exemplo mostra como utilizar uma caixa de diálogo e valores de cartões na mesma para uma extensão de mensagem.	View	View	View	View
Iniciar um novo thread num canal	Este exemplo mostra como utilizar um novo thread num canal com o bot.	View	View	View	View
Localização de aplicações do Teams	Este exemplo mostra como utilizar a localização de aplicações do Teams com o bot e o separador.	View	View	NA	View

Compartilhar via

Canais e conversas de chat em grupo com um bot do Microsoft Teams

Diretrizes de design

Crie novas threads de conversa

Trabalhe com menções

Recupere menções

Adicione menções às suas mensagens

Menção de utilizador

Suporte para Microsoft Entra ID de Objeto e UPN no menção do utilizador

Etiquetar menção

Mencionar etiquetas numa mensagem sms

Mencionar etiquetas num Cartão Ajustável

Parâmetros de Consulta

Código de erro

Redução dos limites

Limitações

Enviar uma mensagem na instalação

Exemplos de bot do Teams

Exemplo de código

Guias passo a passo

Próxima etapa

Confira também

Recursos adicionais