Criar um menu de comandos para o seu bot

Artigo
03/30/2023

Observação

É recomendável que você crie um bot de comando seguindo o guia passo a passo para Criar bot de comando com JavaScript usando a nova ferramenta de desenvolvimento de geração para o Teams. Para obter mais informações sobre o Teams Toolkit, consulte Visão geral do Teams Toolkit para Visual Studio Code e visão geral do Kit de Ferramentas do Teams para Visual Studio.

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 definir um conjunto de comandos principais aos quais o bot pode responder, você pode adicionar um menu de comando com uma lista suspensa 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. Você pode usar o Portal do Desenvolvedor para criá-los ou adicioná-los manualmente no manifesto do aplicativo.

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 comando para o bot usando o Portal do Desenvolvedor:

Abra o Teams e selecione Aplicativos no painel esquerdo. Na página Aplicativos , pesquise Portal do Desenvolvedor e selecione Abrir.
No Portal do Desenvolvedor, selecione a guia Aplicativos . Se você não tiver um pacote de aplicativo existente, poderá criar ou importar um aplicativo existente. Para obter mais informações, confira Portal do Desenvolvedor para Teams.
Selecione Guia Aplicativos , selecione Recursos de aplicativo no painel esquerdo e selecione Bots.
Selecione Adicionar um comando na seção Comandos .
Insira o Comando que aparece como o menu de comando do bot.
Insira a Descrição que aparece no texto de comando no menu. A descrição deve ser uma breve explicação da finalidade do comando.
Selecione a caixa Escopo marcar e selecione Adicionar. Isso define onde o menu de comando deve ser exibido.

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. Você pode manipular comandos de menu no código do bot analisando 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.

Você pode analisar a parte @Mention do texto da mensagem usando 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

Criar um menu de comandos

Criar um menu de comando para seu bot usando o Portal do Desenvolvedor

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