Criar um menu de comandos
Observação
Melhorámos a experiência do menu de comandos como iniciadores de linha de comandos. Recomendamos que consulte os iniciadores de pedidos.
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.
Criar um menu de comandos para o seu bot
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 através da 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.
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.
Criar um menu de comandos para o bot com o Portal do Programador
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 marcar âmbito e, em seguida, selecione Adicionar. Isto define onde o menu de comandos tem de aparecer.
Criar um menu de comando para o bot editando Manifest.json
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 suporta até 10 comandos.
- Crie um único menu de comando que funcione em todos os escopos.
- Crie um menu de comando diferente para cada escopo.
Exemplo de manifesto para menu único para ambos os escopos
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"
}
]
}
]
}
],
...
}
Exemplo de manifesto para o menu para cada escopo
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.
Lidar com comandos de menu no código do bot
Os bots num grupo ou canal só respondem quando são mencionados @botname numa 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 com o Activity nome 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();
Para habilitar o bom funcionamento do código do bot, há algumas práticas recomendadas que você deve seguir.
Práticas recomendadas do menu de comando
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.