Criar um menu de comandos para o seu bot

Artigo
07/16/2024

Observação

Recomenda-se que crie um bot de comandos ao seguir o guia passo a passo para Criar o bot de comandos com JavaScript com a ferramenta de desenvolvimento de nova geração para o Teams. Para obter mais informações sobre o Teams Toolkit, consulte Descrição Geral do Teams Toolkit para Visual Studio Code e Descrição geral do Teams Toolkit para Visual Studio.

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 definir um conjunto de comandos principais aos quais o bot pode responder, pode adicionar um menu de comandos com uma lista pendente de comandos para o bot. A lista de comandos é apresentada aos usuários na área de composição de mensagem quando eles estão em conversa com o bot. Selecione um comando na lista para inserir a cadeia de caracteres de comando na caixa de mensagem de redação e selecione Enviar.

Desktop
Dispositivo móvel

Os menus de comando são definidos no manifesto do aplicativo. Pode utilizar o Portal do Programador para criá-los ou adicioná-los manualmente no manifesto da aplicação.

Um pré-requisito para criar um menu de comando para o bot é que você deve editar um manifesto de aplicativo existente. As etapas para adicionar um menu de comando são as mesmas, independentemente de você criar um novo manifesto ou editar um existente.

Para criar um menu de comandos para o bot com o Portal do Programador:

Abra o Teams e selecione Aplicativos no painel esquerdo. Na página Aplicações , procure Portal do Programador e, em seguida, selecione Abrir.
No Portal do Programador, selecione o separador Aplicações . Se não tiver um pacote de aplicações existente, pode criar ou importar uma aplicação existente. Para obter mais informações, veja Portal do Programador do Teams.
Selecione o separador Aplicações , selecione Funcionalidades da aplicação no painel esquerdo e, em seguida, selecione Bots.
Selecione Adicionar um comando na secção Comandos .
Introduza o Comando que aparece como o menu de comandos do bot.
Introduza a Descrição apresentada no texto do comando no menu. A descrição tem de ser uma breve explicação do objetivo do comando.
Selecione a caixa de verificação Âmbito e, em seguida, selecione Adicionar. Isto define onde o menu de comandos tem de aparecer.

Outra maneira de criar um menu de comando é criá-lo diretamente no arquivo de manifesto ao desenvolver o código-fonte do bot. Para usar esse método, siga estes pontos:

Cada menu dá suporte a até dez comandos.
Crie um único menu de comando que funcione em todos os escopos.
Crie um menu de comando diferente para cada escopo.

O código de exemplo de manifesto para um único menu para ambos os escopos é o seguinte:

{
  ⋮
  "bots":[
    {
      "botId":"[Microsoft App ID for your bot]",
      "scopes": [
        "personal",
        "team"
      ],
      "commandLists":[
        {
          "scopes":[
            "team",
            "personal"
          ],
          "commands":[
            {
              "title":"Help",
              "description":"Displays this help message"
            },
            {
              "title":"Search Flights",
              "description":"Search flights from Seattle to Phoenix May 2-5 departing after 3pm"
            },
            {
              "title":"Search Hotels",
              "description":"Search hotels in Portland tonight"
            },
            {
              "title":"Best Time to Fly",
              "description":"Best time to fly to London for a 5 day trip this summer"
            }
          ]
        }
      ]
    }
  ],
  ...
}

O código de exemplo de manifesto para o menu de cada escopo é o seguinte:

{
  ...
  "bots":[
    {
      "botId":"<Microsoft app ID for your bot>",
      "scopes": [
        "groupChat",
        "team"
      ],
      "commandLists":[
        {
          "scopes":[
            "team"
          ],
          "commands":[
            {
            "title":"help",
            "description":"Displays this help message for channels"
            }
          ]
        },
        {
          "scopes":[
            "groupChat"
          ],
          "commands":[
            {
            "title":"help",
            "description":"Displays this help message for group chat"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Você deve lidar com os comandos do menu em seu código bot, assim como lida com qualquer mensagem dos usuários. Pode processar comandos de menu no código do bot ao analisar a parte @Mention do texto da mensagem.

Os bots em um grupo ou canal respondem somente quando são mencionados @botname em uma mensagem. Cada mensagem recebida por um bot quando em um escopo de grupo ou canal contém seu nome no texto da mensagem. Antes de lidar com o comando que está sendo retornado, a análise de mensagem deve lidar com a mensagem recebida por um bot com seu nome.

Observação

Para lidar com os comandos no código, eles são enviados ao bot como uma mensagem normal. Você deve lidar com eles como lidaria com qualquer outra mensagem de seus usuários. Os comandos no código inserem texto pré-configurado na caixa de texto. Em seguida, o usuário deve enviar esse texto da maneira como faria com qualquer outra mensagem.

Pode analisar a parte @Mention do texto da mensagem através de um método estático fornecido com o Microsoft Bot Framework. É um método da classe Activity chamado RemoveRecipientMention.

O código C# para analisar a parte @Mention do texto da mensagem é o seguinte:

// Remove recipient mention text from Text property.
// Use with caution because this function is altering the text on the Activity.
var modifiedText = turnContext.Activity.RemoveRecipientMention();

Você pode analisar a parte @Mention parte do texto da mensagem usando um método estático fornecido com o Bot Framework. É um método da classe TurnContext chamado removeMentionText.

O código JavaScript para analisar a parte @Mention do texto da mensagem é o seguinte:

// Remove mention text from Text property, this function is altering the text on the Activity.
const modifiedText = TurnContext.removeMentionText(turnContext.activity, turnContext.activity.recipient.id);

Você pode analisar a parte @Mention parte do texto da mensagem usando um método estático fornecido com o Bot Framework. É um método da classe TurnContext chamado remove_recipient_mention.

O código Python para analisar a parte @Mention do texto da mensagem é o seguinte:

# Remove recipient mention text from Text property, this function is altering the text on the Activity.
modified_text = TurnContext.remove_recipient_mention(turn_context.activity)

Para habilitar o bom funcionamento do código do bot, há algumas práticas recomendadas que você deve seguir.

A seguir estão as práticas recomendadas do menu de comando:

Mantenha-o simples: o menu do bot destina-se a apresentar os principais recursos do bot.
Seja breve: as opções de menu não devem ser longas e não devem ser instruções de linguagem natural complexas. Devem ser comandos simples.
Mantenha-o invocável: ações ou comandos do menu do bot devem estar sempre disponíveis, independentemente do estado da conversa ou da caixa de diálogo em que o bot está.

Observação

Se você remover qualquer comando do manifesto, deverá reimplantar seu aplicativo para implementar as alterações. Em geral, todas as alterações no manifesto exigem que você reimplante seu aplicativo.

Próxima etapa

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

Compartilhar via

Criar um menu de comandos

Criar um menu de comandos para o bot com o Portal do Programador

Criar um menu de comando para o bot editando Manifest.json

Exemplo de manifesto para menu único para ambos os escopos

Exemplo de manifesto para o menu para cada escopo

Lidar com comandos de menu no código do bot

Práticas recomendadas do menu de comando

Próxima etapa

Confira também

Comentários

Recursos adicionais