Menus de comando do botBot command menus

Importante

Os exemplos de código nesta seção são baseados em 4,6 e versões posteriores do SDK da estrutura de bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Se você estiver procurando por documentação para versões anteriores, consulte a seção do SDK bots-v3 na pasta recursos da documentação.If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

Observação

Menus de bot não aparecerão em clientes móveis.Bot menus won't appear on mobile clients.

Adicionar menu de comando para seu bot permite que você defina um conjunto de comandos principais que seu bot possa sempre responder.Add command menu for your bot allows you to define a set of core commands your bot can always respond to. A lista de comandos é apresentada ao usuário acima da área de mensagem de redação quando está convertida com o bot.The list of commands is presented to the user above the compose message area when they are conversing with your bot. A seleção de um comando na lista inserirá a cadeia de caracteres de comando na caixa de mensagem de redação, todos os usuários precisarão ser selecionados Enviar.Selecting a command from the list will insert the command string into the compose message box, then all users need to do is select Send.

Menu de comando do bot

Criar um menu de comando para o botCreate a command menu for your bot

Menus de comando são definidos no manifesto do aplicativo.Command menus are defined in your app manifest. Você pode usar o app Studio para ajudá-lo a criá-los ou adicioná-los manualmente.You can either use App Studio to help you create them, or add them manually.

Criando um menu de comando para o bot usando o app StudioCreating a command menu for your bot using App Studio

As instruções aqui presumem que você esteja editando um manifesto de aplicativo existente.The instructions here assume that you'll be editing an existing app manifest. As etapas para adicionar um menu de comando são as mesmas, se você está criando um novo manifesto ou editando um existente.The steps for adding a command menu are the same, whether you're creating a new manifest or editing an existing one.

  1. Abra o app Studio no... menu de estouro no trilho esquerdo de navegação.Open App Studio from the ... overflow menu on the left navigation rail. Se você não tiver o app Studio disponível, você pode baixá-lo.If you don't have App Studio available you can download it. Consulte Installing app Studio para obter mais informações sobre como usar o app Studio.See Installing App Studio for more information on using App Studio.

    App Studio

  2. Uma vez no app Studio, selecione a guia Editor do manifesto .Once in App Studio, select the Manifest editor tab.

  3. Na coluna à esquerda do modo de exibição editor de manifesto na seção recursos , selecione bots.In the left column of the manifest editor view in the Capabilities section, select Bots.

  4. Na coluna à direita do modo de exibição editor de manifesto na seção comandos , selecione o botão Adicionar .In the right column of the manifest editor view in the Commands section, select the Add button.

    Botão Adicionar menu de comando do App Studio

  5. A nova tela de comando será exibida.The New Command screen appears. Insira o texto do comando que você deseja que apareça como o comando de menu e o texto de ajuda que você deseja que apareçam diretamente sob o texto do comando no menu.Enter the Command text that you want to have appear as the menu command, and the Help text that you want to have appear directly under the command text in the menu. Isso deve ser uma breve explicação da finalidade do comando.This should be a brief explanation of the purpose of the command.

  6. Em seguida, selecione o (s) escopo (s) onde deseja que este menu de comando apareça e, em seguida, selecione o botão salvar .Next, select the scope(s) where you want this command menu to appear, then select the Save button.

    Botão Adicionar menu de comando do App Studio

Criar um menu de comando para o bot editando manifest. JSONCreating a command menu for your bot by editing Manifest.json

Outra abordagem válida para a criação de um menu de comando é criá-lo diretamente no arquivo de manifesto ao desenvolver o código-fonte do bot.Another valid approach for creating a command menu is to create it directly in the manifest file while developing your bot source code. Aqui estão algumas coisas que você deve ter em mente ao usar essa abordagem:Here are a few things to keep in mind when using this approach:

  1. Cada menu oferece suporte a até 10 comandos.Each menu supports up to 10 commands.

  2. Você pode criar um único menu de comando que funcionará em todos os escopos.You can create a single command menu that will work in all scopes.

  3. Você pode criar um menu de comando diferente para cada escopoYou can create a different command menu for each scope

Exemplo de manifesto – menu único para ambos os escoposManifest example - single menu for both scopes

{
  ⋮
  "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"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Exemplo de manifesto-menu para cada escopoManifest example - menu for each scope

{
  ...
  "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"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Manipular comandos de menu no seu código de botHandling menu commands in your bot code

Os bots em um grupo ou canal respondem apenas quando são mencionados ("@botname") em uma mensagem.Bots in a group or channel respond only when they are mentioned ("@botname") in a message. Como resultado, todas as mensagens recebidas por um bot quando em um escopo de grupo ou canal conterão seu próprio nome no texto da mensagem retornado.As a result, every message received by a bot when in a group or channel scope will contain its own name in the message text returned. Você precisa garantir que as alças de análise da mensagem antes de manipular o comando retornado.You need to ensure your message parsing handles that before handling the command being returned.

Você pode analisar a Activity RemoveRecipientMention ** @** parte de menção do texto da mensagem usando um método estático fornecido com o Microsoft bot Framework — um método da classe chamado.You can parse out the @Mention portion of the message text using a static method provided with the Microsoft Bot Framework — a method of the Activity class named RemoveRecipientMention.

var modifiedText = turnContext.Activity.RemoveRecipientMention();

Práticas recomendadas do menu de comandosCommand menu best practices

  • Mantenha-o simples: o menu bot é destinado a apresentar os principais recursos do bot.Keep it simple: The bot menu is meant to present the key capabilities of your bot.
  • Mantenha- o em breve: as opções de menu não devem ser extremamente longas e instruções de linguagem natural complexas, que devem ser comandos simples.Keep it short: Menu options shouldn’t be extremely long and complex natural language statements — they should be simple commands.
  • Mantenha-o em invocação: as ações/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á.Keep it invokable: Bot menu actions/commands should always be available, regardless of the state of the conversation or the dialog the bot is in.