Generar extensiones de mensaje

Las extensiones de mensaje permiten a los usuarios interactuar con el servicio web a través de botones y formularios dentro del cliente de Microsoft Teams. Los usuarios pueden buscar o iniciar acciones en un sistema externo desde el área de redacción de mensajes, el cuadro de comandos o directamente desde un mensaje. Los resultados de estas interacciones se pueden devolver al cliente de Teams como una tarjeta con formato enriquecido.

Importante

Las extensiones de mensaje están disponibles en los entornos de government community cloud (GCC), GCC-High y Department of Defense (DOD).

En este documento se proporciona información general sobre las extensiones de mensaje, las tareas ejecutadas en varios escenarios, el funcionamiento de las extensiones de mensaje, los comandos de acción y búsqueda y la desplegamiento de vínculos.

En la imagen siguiente se muestran las ubicaciones desde las que se pueden invocar las extensiones de mensaje:

Nota:

@mentioning no se admiten las extensiones de mensaje en el cuadro de redacción.

Escritorio

Móvil

Escenarios en los que se usan extensiones de mensajería

Escenario	Ejemplo
Necesita un sistema externo para realizar una acción y devolver el resultado a la conversación.	Reserve un recurso y permita que el canal esté al corriente de la franja horaria reservada.
Debe buscar algo en un sistema externo y compartir los resultados con la conversación.	Busque un elemento de trabajo en Azure DevOps y compárelo con el grupo como una tarjeta adaptable.
Quiere completar una tarea compleja que implique varios pasos o una gran cantidad de información en un sistema externo y compartir los resultados con una conversación.	Cree un error en su sistema de seguimiento basado en un mensaje de Teams, asigne ese error a un usuario y envíe una tarjeta al hilo de conversación con los detalles del error.

Descripción del funcionamiento de las extensiones de mensajería

Una extensión de mensaje consta de un servicio web que hospeda y un manifiesto de aplicación, que especifica la ubicación en el cliente de Teams donde se invoca el servicio web. El servicio web usa el esquema de mensajería de Bot Framework y el protocolo de comunicación seguro, por lo que debe registrar el servicio web como bot en Bot Framework.

Nota:

Aunque es posible crear manualmente el servicio web, se recomienda usar Bot Framework SDK para trabajar con el protocolo.

En el manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams), se define una única extensión de mensaje con hasta 10 comandos diferentes. Cada comando define un tipo, como acción o búsqueda y las ubicaciones del cliente desde donde se invoca. Las ubicaciones de invocación incluyen el área del mensaje de redacción, la barra de comandos y el mensaje. Al invocar, el servicio web recibe un mensaje HTTPS con una carga JSON con toda la información pertinente. Responda con una carga JSON para informar al cliente de Teams de la siguiente interacción que se va a habilitar.

Tipos de comandos de extensión de mensaje

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. Algunas interacciones, como la autenticación y la configuración, están disponibles para ambos tipos de comandos.

Comandos de acción

Los comandos de acción se usan para presentar a los usuarios un elemento emergente modal para recopilar o mostrar información. Cuando el usuario envía el formulario, el servicio web responde insertando un mensaje en la conversación directamente o en el área de redacción del mensaje. Posteriormente, el usuario puede enviar el mensaje. Para flujos de trabajo más complejos, puede vincular varios formularios entre sí.

Los comandos de acción se desencadenan desde el área del mensaje de redacción, el cuadro de comandos o un mensaje. Cuando se invoca el comando desde un mensaje, la carga JSON inicial enviada al bot incluye todo el mensaje desde el que se invocó. En la imagen siguiente se muestra el cuadro de diálogo de comando de acción de extensión de mensaje (denominado módulo de tareas en TeamsJS v1.x):

Comandos de búsqueda

Los comandos de búsqueda permiten a los usuarios buscar información manualmente en un sistema externo a través de un cuadro de búsqueda o pegando un vínculo a un dominio supervisado en el área del mensaje de redacción e insertan los resultados de la búsqueda en un mensaje. En un flujo de comandos de búsqueda simple, el mensaje de invocación inicial incluye la cadena de búsqueda enviada por el usuario. Responderá con una lista de tarjetas y vistas previas de tarjetas. El cliente Teams provee una lista de vistas previas de tarjetas para el usuario. Cuando el usuario seleccione una tarjeta, la tarjeta a tamaño completo se insertará en el área de redacción del mensajes.

Las tarjetas se desencadenan desde el área del mensaje de redacción o el cuadro de comandos, pero no desde un mensaje. No se pueden desencadenar desde un mensaje. En la imagen siguiente se muestra el cuadro de diálogo del comando de búsqueda de extensión de mensaje:

Nota:

Para obtener más información sobre las tarjetas, consulte qué son las tarjetas.

Apertura de vínculos

Nota:

La desplegamiento de vínculos solo se admite para extensiones de mensajes basadas en bots.

Cuando se pega una dirección URL en el área del mensaje de redacción, se invoca un servicio web. Esta funcionalidad se conoce como apertura de vínculos. Puede suscribirse para recibir una invocación cuando las direcciones URL que contienen un dominio específico se pegan en el área del mensaje de redacción. El servicio web puede desplegar la dirección URL en una tarjeta detallada, lo que proporciona más información que la tarjeta de vista previa del sitio web estándar. Puede agregar botones para permitir que los usuarios realicen acciones inmediatamente sin salir del cliente de Teams. Las siguientes imágenes muestran la característica de desplegamiento de vínculos cuando se pega un vínculo en una extensión de mensaje:

Generar extensiones de mensaje

Para compilar una extensión de mensaje, si aún no tiene una, hay dos maneras:

• Compilación de extensiones de mensajes mediante API (basada en API): puede crear fácilmente una extensión de mensaje a partir de una API existente. Se requiere un documento de Descripción de OpenAPI (OAD) para este método.

• Compilación de extensiones de mensajes mediante Bot Framework (basado en bots): si quiere una experiencia conversacional uno a uno, puede crear una nueva extensión de mensaje a partir de un bot.

La tabla siguiente le ayuda a seleccionar un tipo de extensión de mensaje para empezar:

Extensión de mensaje basada en API

• Más sencillo y rápido de crear y mantener.
• La extensión de mensaje usa una API.
• No se requiere código ni recursos adicionales para la lógica del bot.
• Ideal para escenarios en los que la extensión de mensaje solo necesita comunicarse con un servicio web y no necesita ninguna lógica compleja ni administración de estados.
• El tráfico se privatiza, ya que no dependen de la infraestructura de bots de Azure.
• Admite comandos de búsqueda.

Extensión de mensaje basada en bots

• Más flexible.
• La extensión de mensaje usa Bot Framework.
• Puede aprovechar todas las funcionalidades de un bot.
• Ideal para escenarios en los que la extensión de mensaje necesita comunicarse con varios servicios, administrar interacciones de usuario o lógica complejas o mantener el estado entre sesiones.
• Admite comandos de acción, comandos de búsqueda y desplegamiento de vínculos.

Seleccione una opción para empezar a compilar una extensión de mensaje:

Ejemplo de código

Ejemplo de nombre	Descripción	.NET	Node.js	Python	Manifiesto
Extensión de mensajería con comandos basados en acciones	En este ejemplo se muestra cómo definir comandos de acción, crear cuadros de diálogo y responder a la acción de envío del cuadro de diálogo.	View	View	View	View
Extensión de mensajería con comandos basados en búsquedas	En este ejemplo se muestra cómo crear una extensión de mensaje basada en búsqueda. Busca paquetes nuget y muestra los resultados en la extensión de mensajería basada en búsquedas.	View	View	View	Ver
Vista previa de la acción de extensión de mensaje	En este ejemplo se muestra cómo usar la versión preliminar de la acción en Extensiones de mensajería mediante Bot Framework v4.	View	View	ND	View
Acción de extensión de mensajería para la programación de tareas	En este ejemplo se muestra cómo programar una tarea desde el comando de acción de extensión de mensaje y obtener una tarjeta de recordatorio en una fecha y hora programadas.	View	View	ND	Ver