Compilación de extensiones de mensaje mediante Bot Framework

Las extensiones de mensaje creadas con Bot Framework (basadas en bots) usan un servicio web como bot. Puede usar extensiones de mensaje para permitir que los usuarios interactúen con el servicio web desde distintas ubicaciones del cliente de Teams, como el área de redacción del mensaje, el cuadro de comandos o directamente desde un mensaje y enviar datos estructurados, como tarjetas.

La extensión de mensajes basada en bots aprovecha el esquema de mensajería de Bot Framework y el protocolo de comunicación seguro. El bot se define en el manifiesto de la aplicación para la aplicación teams y también puede definir diferentes tipos de comandos para la extensión de mensaje, como comandos de acción o comandos de búsqueda.

Hay dos tipos de comandos de extensión de mensajería: comando de acción y comando de búsqueda. El tipo de comando de extensión de mensaje define los elementos de la interfaz de usuario y los flujos de interacción disponibles para su servicio web. Puede usar un comando de búsqueda o un comando de acción para interactuar con el servicio web a través de un bot en Teams.

Comandos de búsqueda

Los comandos de búsqueda de extensión de mensaje permiten a los usuarios buscar sistemas externos e insertar los resultados de esa búsqueda en un mensaje en forma de tarjeta. Este documento le guía sobre cómo seleccionar ubicaciones de invocación de comandos de búsqueda y agregar el comando de búsqueda al manifiesto de la aplicación.

Nota:

El límite de tamaño de la tarjeta de resultados es de 28 KB. La tarjeta no se envía si su tamaño supera los 28 KB.

Vea el siguiente vídeo para obtener información sobre cómo definir comandos de búsqueda de extensión de mensaje:

El comando de búsqueda de una extensión de mensaje se configura mediante la composeExtensions.commands propiedad y el query tipo en el manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams). Las descripciones de comandos y parámetros mejoran la facilidad de uso y la eficacia de una extensión de mensaje. Una buena descripción del comando ofrece un resumen claro y conciso de las características de la aplicación.

El código siguiente es un ejemplo de la composeExtensions propiedad que define un comando de búsqueda:

{
 "composeExtensions": [
    {
      "botId": "eccdf132-0900-4d36-936b-dec5e6357f11",
      "commands": [
        {
          "id": "Dev",
          "type": "query",
          "title": "Jedi",
          "description": "May the force be with you",
          "initialRun": true,
          "fetchTask": false,
          "context": [
            "commandBox",
            "compose",
            "message"
          ],
          "parameters": [
            {
              "name": "Luke",
              "title": "Skywalker",
              "description": "Jedi master",
              "inputType": "text"
            }
          ]
        }
      ],
      "canUpdateConfiguration": true
    }
  ],

Parameters

Debe agregar los parámetros siguientes a la composeExtensions.commands matriz de objetos:

Nombre de propiedad	Objetivo	¿Necesario?	Versión del manifiesto
id	Identificador único que se asigna al comando de búsqueda. La solicitud de usuario incluye este id.	Sí	1.0
title	Nombre del comando. Este valor aparece en la interfaz de usuario (UI).	Sí	1.0
description	Texto de ayuda que indica lo que hace este comando. Este valor aparece en la interfaz de usuario.	Sí	1.0
semanticDescription	Descripción semántica del comando para su consumo por parte del modelo de lenguaje grande.	No	1.17
type	Tipo de comando. El valor predeterminado es query.	No	1.4
initialRun	Si esta propiedad se establece en true, indica que este comando debe ejecutarse en cuanto el usuario seleccione este comando en la interfaz de usuario.	No	1.0
context	Matriz opcional de valores que define el contexto en el que está disponible la acción de búsqueda. Los valores posibles sonmessage, compose o commandBox. El valor predeterminado es compose,commandBox.	No	1,5

Debe agregar los siguientes detalles del parámetro de búsqueda que definen el texto visible para el usuario en el cliente de Teams:

Nombre de propiedad	Objetivo	¿Es obligatoria?	Versión mínima del manifiesto
parameters	Define una lista estática de parámetros para el comando.	No	1.0
parameter.name	Describe el nombre del parámetro. parameter.name se envía al servicio en la solicitud del usuario.	Sí	1.0
parameter.description	Describe los propósitos del parámetro o el ejemplo del valor que se debe proporcionar. Este valor aparece en la interfaz de usuario.	Sí	1.0
parameter.semanticDescription	Descripción semántica del parámetro para su consumo por parte del modelo de lenguaje grande.	No	1.17
parameter.title	Título o etiqueta de parámetros breves fáciles de usar.	Sí	1.0
parameter.inputType	Establezca en el tipo de entrada necesaria. Entre los valores posibles se incluyen , , , , , toggletime. datenumbertextareatext El valor predeterminado está establecido en text.	No	1.4
parameters.value	Valor inicial del parámetro. Actualmente no se admite el valor	No	1,5

Para obtener más información, consulte esquema de manifiesto de aplicación.

Paso siguiente

Definición del comando de búsqueda de extensión de mensaje

Comandos de acción

Nota:

Cuando se inicia una acción de mensaje, los detalles de los datos adjuntos no se envían como parte de la turncontext actividad de invocación.

Los comandos de acción permiten presentar a los usuarios un elemento emergente modal denominado módulo de tareas en Teams. El módulo de tareas recopila o muestra información, procesa la interacción y envía la información de vuelta a Teams. Este documento le guía sobre cómo seleccionar ubicaciones de invocación de los comandos de acción, crear el módulo de tareas, enviar el mensaje final o tarjeta, crear un comando de acción mediante App Studio o crearlo manualmente.

El comando action de una extensión de mensaje se configura mediante la composeExtensions.commands propiedad y action escribe en el manifiesto de la aplicación.

El código siguiente es un ejemplo de la composeExtensions propiedad que define un comando de acción:

"composeExtensions": [
        {
            "botId": "xxxxxx-xxx-bot-ID-xxxxxxxx}",
            "commands": [
                {
                    "id": "createCard",
                    "context": [
                        "compose",
                        "message",
                        "commandBox"
                    ],
                    "description": "Command to run action to create a Card from Compose Box",
                    "title": "Create Card",
                    "type": "action",
                    "parameters": [
                        {
                            "name": "title",
                            "title": "Card title",
                            "description": "Title for the card",
                            "inputType": "text"
                        },
                        {
                            "name": "subTitle",
                            "title": "Subtitle",
                            "description": "Subtitle for the card",
                            "inputType": "text"
                        },
                        {
                            "name": "text",
                            "title": "Text",
                            "description": "Text for the card",
                            "inputType": "textarea"
                        }
                    ]
                }
            ]
        }
    ]

Parameters

Debe agregar los parámetros siguientes a la composeExtensions.commands matriz de objetos:

Nombre de propiedad	Objetivo	¿Necesario?	Versión del manifiesto
id	Identificador único que se asigna a este comando. La solicitud de usuario incluye este id.	Sí	1.0
title	Nombre del comando. Este valor aparece en la interfaz de usuario.	Sí	1.0
type	Tipo de extensión de mensaje. El valor predeterminado es action.	No	1.4
fetchTask	true Establézcalo en para una tarjeta adaptable o una vista web incrustada para el módulo de tareas yfalse para una lista estática de parámetros o al cargar la vista web mediante .taskInfo	No	1.4
context	Matriz opcional de valores que define desde dónde se invoca la extensión de mensaje. Los valores posibles sonmessage, compose o commandBox. El valor predeterminado es ["compose", "commandBox"].	No	1,5

Si usa una lista estática de parámetros, también debe agregar los parámetros siguientes:

Nombre de propiedad	Objetivo	¿Es obligatoria?	Versión mínima del manifiesto
parameters	Describe la lista estática de parámetros para el comando. Solo se usa cuando fetchTask es false.	No	1.0
parameter.name	Describe el nombre del parámetro. Esto se envía al servicio en la solicitud del usuario.	Sí	1.0
parameter.description	Describe los propósitos del parámetro o el ejemplo del valor que se debe proporcionar. Este valor aparece en la interfaz de usuario.	Sí	1.0
parameter.title	Título o etiqueta de parámetros breves fáciles de usar.	Sí	1.0
parameter.inputType	Establezca en el tipo de entrada necesaria. Los valores posibles incluyen text, textarea, number, date, time, toggle. El valor predeterminado se establece en text.	No	1.4

Si usa una vista web incrustada, opcionalmente puede agregar el objeto para capturar la taskInfo vista web sin llamar directamente al bot. Si selecciona esta opción, el comportamiento es similar al del uso de una lista estática de parámetros. En que la primera interacción con el bot es responder a la acción de envío del módulo de tareas. Si usa un taskInfo objeto, debe establecer el fetchTask parámetro en false.

Nombre de propiedad	Objetivo	¿Es obligatoria?	Versión mínima del manifiesto
taskInfo	Especifique el módulo de tareas que se va a cargar previamente al usar un comando de extensión de mensajería.	No	1.4
taskInfo.title	Título del módulo de tareas inicial.	No	1.4
taskInfo.width	Ancho del módulo de tareas, ya sea un número en píxeles o un diseño predeterminado, como large, medium o small.	No	1.4
taskInfo.height	Alto del módulo de tareas, ya sea un número en píxeles o un diseño predeterminado, como large, medium o small.	No	1.4
taskInfo.url	Dirección URL inicial de la vista web.	No	1.4

Para obtener más información, consulte esquema de manifiesto de aplicación.

Paso siguiente

Definir comandos de acción de extensión de mensajería

Vea también

• Acciones universales para extensiones de mensajes basadas en búsqueda
• Extensión de mensaje basada en API