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

Importante

Os exemplos de código nesta seção são baseados na versão 4.6 e versões posteriores do SDK do Bot Framework. Se você estiver procurando documentação para versões anteriores, consulte a seção bots – v3 SDK na pasta SDKs Herdados 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 ele é instalado em uma equipe, o bot tem acesso a detalhes sobre essa equipe e a lista completa de canais.

Bots em um grupo ou canal só recebem mensagens quando são mencionados @botname. Eles não recebem nenhuma outra mensagem enviada para a conversa. O bot deve ser @mentioned diretamente. O bot não recebe uma mensagem quando a equipe ou o canal é mencionado ou quando alguém responde a uma mensagem do bot sem @mentioning ele.

Observação

• O RSC para todas as mensagens de chat está disponível apenas na versão prévia do desenvolvedor público.
• Usando o RSC (consentimento específico do recurso), os bots podem receber todas as mensagens de canal em equipes em que ele está instalado sem ser @mentioned. Para obter mais informações, confira receber todas as mensagens de canal com o RSC.
• No momento, não há suporte para postar uma mensagem ou um cartão adaptável em um canal privado.

Confira o vídeo a seguir para saber mais sobre conversas de chat em grupo e canal 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. Às vezes, é difícil diferenciar entre duas conversas. Se a conversa estiver em thread, será mais fácil organizar e gerenciar conversas diferentes 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 uma @mention com seu 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.

Você também deve remover o @mentions do conteúdo da mensagem que seu 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 confie no texto na 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 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:

C#

• Referência do SDK

• Referência de código de exemplo

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

TypeScript

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();
});

JSON

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

Python

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

Há dois tipos de menções:

• Menção de usuário
• Marca menção

Menção de usuário

Seu bot pode menção outros usuários em mensagens postadas 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:

C#

• Referência do SDK
• Referência de código de exemplo

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

TypeScript

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();
});

JSON

O campo text no objeto da matriz entities deve corresponder a uma parte do campo text da mensagem. Se não o fizer, o menção será ignorado.

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

Python

• Referência do SDK
• Referência de código de exemplo

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.

Marca menção

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

Observação

• As menções de marca estão disponíveis apenas na versão prévia do desenvolvedor público.
• Há suporte para menções de marca em clientes web e área de trabalho do Teams. No entanto, não há suporte no cliente móvel do Teams.
• Não há suporte para menções de marca em locatários do GCC (Government Community Cloud), GCC-High e Departamento de Defesa (DoD).

Mencionar marcas em uma mensagem de texto

mention.properties No objeto, adicione a propriedade 'type': 'tag'. Se a propriedade 'type': 'tag' não for adicionada, o bot tratará o menção como um menção de usuário.

Exemplo:

O type:tag é adicionado como um Properties no 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); 

Marcas de menção em um cartão adaptável

No esquema Cartão Adaptável, sob o mentioned objeto, adicione a "type": "tag" propriedade. Se a "type": "tag" propriedade não for adicionada, o bot tratará o menção como um menção de usuário.

Você pode obter a lista das marcas disponíveis no canal usando a API Listar 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 com suporte é tag.
id	O identificador exclusivo para a marca. Para obter mais informações, consulte teamworkTag.

Código de erro

Código de status	Código de erro	Valores de mensagem	Repita a solicitação	Ação do desenvolvedor
400	Código: Bad Request	A marca mencionada com iD {id string} não existe na equipe atual A marca só pode ser mencionada no canal Marca mencionada inválida porque não existe nenhuma marca na equipe	Não	Reavaliar a carga de solicitação para erros. Verifique a mensagem de erro retornada para obter detalhes.
502	Código: Bad Gateway	ID inválida do grupo de equipe ID do locatário malformado para a marca A ID de menção não pode ser resolvida	Não	Tente novamente manualmente.

Redução dos limites

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

Verifique se você não excede os limites de limitação para evitar a entrega de mensagens com falha. Por exemplo, um bot pode enviar apenas duas mensagens com marcas menção em uma janela de cinco segundos e cada mensagem pode ter apenas até 10 marcas.

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

Escopo	Tipo de janela	Número de marcas por mensagem	Janelas de tempo (ss)	Número máximo de mensagens por janela de tempo
Por bot por thread	Curto	10	5	2
	Longas	10	60	5
Todos os bots por thread	Curto	10	5	4
	Longo	10	60	5

Limitações

• Há suporte para menções de marca somente no fluxo de mensagens de bot para cliente com texto e Cartão Adaptável.
• Não há suporte para menções de marca em canais compartilhados e privados.
• Não há suporte para menções de marca em conectores.
• As menções de marca não dão suporte ao fluxo de invocação em um 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.

Você pode enviar uma mensagem pessoal para cada membro da equipe quando o bot for adicionado. Para fazer isso, busque a lista de equipes e envie uma mensagem direta a cada usuário.

Observação

Verifique se a mensagem enviada pelo bot é relevante e adiciona valor à mensagem inicial e não envia spam aos usuários.

Não envie uma mensagem nos seguintes casos:

• Quando a equipe é grande, por exemplo, maior que 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, consulte os seguintes exemplos do Teams para Bot Framework:

Nome de exemplo	Descrição	.NET	Node.js	Python	Manifesto
Bot de conversas do Teams	Este exemplo mostra como usar diferentes eventos de conversa de bot disponíveis na estrutura do bot v4 para escopo pessoal e de equipes.	View	View	View	View
Autenticação com OAuthPrompt	Este exemplo mostra autenticação e mensagens básicas no Bot Framework v4.	View	View	View	View
Upload de arquivo do Teams	Este exemplo mostra como usar arquivos com um bot em uma conversa individual.	View	View	View	View
Módulo de tarefa	Este exemplo mostra como usar um módulo de tarefa e valores de cartões nele para uma extensão de mensagem.	View	View	View	View
Iniciar novo tópico em um canal	Este exemplo mostra como usar um novo thread em um canal usando bot.	View	View	View	View
Localização do aplicativo Teams	Este exemplo mostra como usar a localização do aplicativo teams usando bot e guia.	View	View	NA	View

Guias passo a passo

Siga o guia passo a passo, crie o bot de conversa do Teams.

Próxima etapa

Inscreva-se em eventos de conversa

Confira também

• Obter contexto do Teams
• Criar canal privado em nome do usuário
• Conectar um bot ao canal Webchat