Crear un menú de comandos
Nota:
Hemos mejorado la experiencia del menú de comandos como inicios del símbolo del sistema. Le recomendamos que consulte los inicios de aviso.
Para definir un conjunto de comandos principales a los que el bot puede responder, puede agregar un menú de comandos con una lista desplegable de comandos para el bot. La lista de comandos se presenta a los usuarios en el área del redacción del mensaje cuando están en una conversación con el bot. Seleccione un comando de la lista para insertar la cadena de comando en el cuadro de mensaje de redacción y seleccione Enviar.
Crear un menú de comandos para el bot
Nota:
Se recomienda crear un bot de comandos siguiendo la guía paso a paso para compilar un bot de comandos con JavaScript mediante la herramienta de desarrollo de nueva generación para Teams. Para obtener más información sobre el kit de herramientas de Teams, consulte Introducción al kit de herramientas de Teams para Visual Studio Code y Información general del kit de herramientas de Teams para Visual Studio.
Importante
Los ejemplos de código de esta sección se basan en la versión 4.6 y versiones posteriores del SDK de Bot Framework. Si busca documentación para versiones anteriores, consulte la sección bots - v3 SDK en la carpeta SDK heredados de la documentación.
Los menús de comandos se definen en el manifiesto de la aplicación. Puede usar el Portal para desarrolladores para crearlos o agregarlos manualmente en el manifiesto de la aplicación.
Creación de un menú de comandos para el bot mediante el Portal para desarrolladores
Un requisito previo para crear un menú de comandos para el bot es que debe editar un manifiesto de aplicación existente. Los pasos para agregar un menú de comandos son los mismos, sin importar si crea un nuevo manifiesto o si edita uno existente.
Para crear un menú de comandos para el bot mediante el Portal para desarrolladores:
Abra Teams y seleccione Aplicaciones en el panel izquierdo. En la página Aplicaciones , busque Portal para desarrolladores y, a continuación, seleccione Abrir.
En Portal para desarrolladores, seleccione la pestaña Aplicaciones . Si no tiene un paquete de aplicación existente, puede crear o importar una aplicación existente. Para obtener más información, consulte Portal para desarrolladores para Teams.
Seleccione la pestaña Aplicaciones , seleccione Características de la aplicación en el panel izquierdo y, a continuación, bots.
Seleccione Agregar un comando en la sección Comandos .
Escriba el comando que aparece como el menú de comandos del bot.
Escriba la descripción que aparece bajo el texto del comando en el menú. Descripción debe ser una breve explicación del propósito del comando.
Active la casilla Ámbito y, a continuación, seleccione Agregar. Esto define dónde debe aparecer el menú de comandos.
Edite Manifest.json para crear un menú de comandos para el bot
Otra manera de crear un menú de comandos es crearlo directamente en el archivo de manifiesto mientras desarrolla el código fuente del bot. Para usar este método, siga estos puntos:
- Cada menú admite hasta 10 comandos.
- Cree un único menú de comandos que funcione en todos los ámbitos.
- Cree un menú de comandos diferente para cada ámbito.
Ejemplo de manifiesto para un solo menú para ambos ámbitos
El código de ejemplo del manifiesto para un menú único para ambos ámbitos es el siguiente:
{
⋮
"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"
}
]
}
]
}
],
...
}
Ejemplo de manifiesto para el menú de cada ámbito
El código de ejemplo del manifiesto para el menú para cada ámbito es el siguiente:
{
...
"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"
}
]
}
]
}
],
...
}
Debe controlar los comandos del menú en el código del bot del mismo modo que controla cualquier mensaje de los usuarios. Puede controlar los comandos de menú en el código del bot analizando la parte @Mention del texto del mensaje.
Control de comandos de menú en el código del bot
Los bots de un grupo o canal solo responden cuando se mencionan @botname en un mensaje. Cada mensaje recibido por un bot cuando se encuentra en un ámbito de grupo o canal contiene su nombre en el texto del mensaje. Antes de controlar el comando que se devuelve, el análisis de mensajes debe controlar el mensaje recibido por un bot con su nombre.
Nota:
Para controlar los comandos en el código, se envían al bot como un mensaje normal. Debe controlarlos como controlaría cualquier otro mensaje de los usuarios. Los comandos en el código insertan texto preconfigurado en el cuadro de texto. A continuación, el usuario debe enviar ese texto como lo hace con cualquier otro mensaje.
Puede analizar la parte @Mention del texto del mensaje mediante un método estático proporcionado con el Microsoft Bot Framework. Es un método de la Activity clase denominada RemoveRecipientMention.
El código de C# para analizar la parte @Mention del texto del mensaje es la siguiente:
// 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 el funcionamiento sin problemas del código del bot, hay algunos procedimientos recomendados que debe seguir.
Procedimientos recomendados para eel menú de comandos
A continuación, se describen los procedimientos recomendados para el menú de comandos:
- Mantenga la simplicidad: el menú del bot está diseñado para presentar las funcionalidades clave del bot.
- Sea breve: las opciones de menú no deben ser largas y no deben ser instrucciones de lenguaje natural complejas. Deben ser comandos simples.
- Mantenga la invocabilidad: las acciones o comandos del menú del bot siempre deben estar disponibles, independientemente del estado de la conversación o del cuadro de diálogo en el que se encuentra el bot.
Nota:
Si quita los comandos del manifiesto, debe volver a implementar la aplicación para actualizar los cambios. En general, cualquier cambio en el manifiesto requiere que vuelva a implementar la aplicación.