Crear un menú de comandos para el bot

Artículo
03/30/2023

Nota:

Se recomienda crear un bot de comandos siguiendo la guía paso a paso de Compilación del 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.

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.

Escritorio
Móvil

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.

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.

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 diez comandos.
Cree un único menú de comandos que funcione en todos los ámbitos.
Cree un menú de comandos diferente para cada ámbito.

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

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.

Los bots de un grupo o canal solo responden cuando se menciona @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 clase Activity 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();

Puede analizar la parte @Mención del texto del mensaje mediante un método estático proporcionado con Bot Framework. Es un método de la clase TurnContext denominada removeMentionText.

El código JavaScript para analizar la parte @Mention del texto del mensaje es el siguiente:

// 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);

Puede analizar la parte @Mención del texto del mensaje mediante un método estático proporcionado con Bot Framework. Es un método de la clase TurnContext denominada remove_recipient_mention.

El código de Python para analizar la parte @Mention del texto del mensaje es el siguiente:

# 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 el funcionamiento sin problemas del código del bot, hay algunos procedimientos recomendados que debe seguir.

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.

Paso siguiente

Canal y conversaciones de chat de grupo con un bot

Compartir a través de

Crear un menú de comandos

Creación de un menú de comandos para el bot mediante el Portal para desarrolladores

Edite Manifest.json para crear un menú de comandos para el bot

Ejemplo de manifiesto para un solo menú para ambos ámbitos

Ejemplo de manifiesto para el menú de cada ámbito

Control de comandos de menú en el código del bot

Procedimientos recomendados para eel menú de comandos

Paso siguiente

Consulte también

Comentarios

Recursos adicionales