Microsoft Teams
Si se configura un canal de Microsoft Teams, los usuarios pueden chatear con el asistente digital (o una aptitud independiente) a través de la interfaz de usuario de Microsoft Teams.
Este es el proceso para configurar un canal:
- En el portal de desarrollador de Microsoft Teams, cree una aplicación y agregue un bot a esa aplicación.
- Con el identificador y la contraseña de aplicación del bot, cree un canal en Digital Assistant.
- Copie la URL del webhook que se genera al crear el canal y agréguelo al bot.
- Pruebe el asistente digital en Microsoft Teams.
Las aptitudes y los asistentes digitales que exponga a través de los canales de Microsoft Teams también se pueden incluir en los chats de grupo. Consulte Chats de grupo.
Paso 1: creación de un bot
Para que el asistente digital (o aptitud independiente) esté disponible en Microsoft Teams, debe crear lo siguiente a través del portal de desarrollador de equipos:
- Una aplicación de Microsoft Teams. Esta aplicación es el contenedor para el bot que cree y es el modo de acceder al bot en Teams.
- Un bot. Este es el artefacto dentro de la aplicación que se comunica con Oracle Digital Assistant
El portal de desarrolladores de Teams no está disponible para algunos tipos de inquilinos de Microsoft, como los inquilinos de GCC-High y del Departamento de Defensa (DoD). Si está trabajando con un inquilino de este tipo, puede utilizar un inquilino normal para crear la aplicación, descargar la aplicación y, a continuación, utilizar Microsoft Graph para cargar la aplicación en su nube nacional. Consulte Portal de desarrolladores para equipos y Despliegues nacionales en la nube en el sitio de Microsoft para obtener más información.
Realice los siguientes pasos:
- Vaya a https://dev.teams.microsoft.com/home e inicie sesión con su cuenta de Microsoft.
- En la navegación izquierda, haga clic en Aplicaciones.
- Haga clic en + Nueva Aplicación.
- En el cuadro de diálogo Agregar aplicación, rellene el nombre que desea utilizar para la aplicación tal y como aparecerá en Microsoft Teams y, a continuación, haga clic en Agregar.
(Esta aplicación encapsulará el bot que creará más tarde).
- En la página Información básica, rellene los campos necesarios restantes, excepto el ID de aplicación (cliente) y haga clic en Guardar.
Nota
Este campo solo es necesario si configura el bot para la conexión única. Consulte Configuración de conexión única para canales de Microsoft Teams. - En la navegación izquierda de la página, en la sección Configurar, seleccione Funciones de aplicación.
- Haga clic en Bot.
- Haga clic en el enlace Crear un nuevo bot.
- En la página Gestión de bots, haga clic en + Nuevo bot.
- En el cuadro de diálogo Agregar bot, introduzca un nombre para el bot.
- En la sección Canales de la página, seleccione la casilla de control Microsoft Teams y haga clic en Guardar.
- En la sección Secretos de cliente, seleccione Agregar un secreto de cliente para el bot.
- Copiar el valor del secreto de cliente generado y guardarlo en un lugar seguro del sistema.
- En la sección Secretos de cliente de la página, haga clic con el botón derecho en el enlace Azure para abrir la página Registros de aplicación de Azure Active Directory en un separador de explorador independiente.
- En la página Registros de aplicaciones, seleccione el recurso de bot que ha creado.
- En la guía izquierda, seleccione Autenticación.
- En la sección Tipos de cuenta soportados de la página, seleccione la opción multiinquilino (Cuentas en cualquier directorio organizativo (cualquier inquilino de Microsoft Entra ID - Multiinquilino).
- Si desea poder utilizar eventos externos para enviar mensajes a los usuarios a través de un canal de Microsoft Teams, agregue permisos para recuperar el perfil de usuario mediante la API de Microsoft Graph. (La función de eventos externos utiliza datos de usuario almacenados en caché de conversaciones anteriores para generar notificaciones o iniciar conversaciones de forma proactiva con el usuario). Estos son los pasos para agregar esos permisos:
- En la navegación izquierda de la página Registros de aplicación del bot, seleccione Permisos de API.
- Haga clic en Agregar un permiso.
- En el cuadro de diálogo Solicitar permisos de API, seleccione Microsoft Graph.
- Seleccione Los permisos de la aplicación.
- Seleccione el permiso Directory.Read.All y haga clic en Agregar permisos.
- Una vez que el permiso aparezca en la lista Permisos configurados, seleccione el permiso, haga clic en Otorgar consentimiento de administrador para... y, a continuación, haga clic en Sí en el cuadro de diálogo Otorgar confirmación de consentimiento de administrador.
-
Vuelva al separador en el que tiene el portal del desarrollador abierto en el explorador.
-
En la navegación de la izquierda, haga clic en Aplicaciones y, a continuación, seleccione la aplicación.
-
En la navegación izquierda de la aplicación, seleccione App features.
-
Haga clic en el mosaico Bot.
-
En la lista desplegable que aparece debajo de Seleccionar un bot existente, seleccione el bot que acaba de crear.
-
Una vez más, en la navegación izquierda de la aplicación, seleccione Funciones de aplicación.
-
En el título Bot, copie el ID de bot y guárdelo en un archivo de texto.
Nota
Puede que tenga que transcribir manualmente el ID del bot.Necesitará este identificador cuando cree el canal en Digital Assistant.
- En la sección Ámbitos de la página, seleccione Personal.
(También puede seleccionar otros ámbitos, pero el bot debe responder Personal).
-
Haga clic en Guardar.
-
De manera opcional, en la navegación izquierda de la página, en la sección Configure (Configurar), seleccione Domains (Dominios) y agregue los dominios de los que pueden provenir los usuarios del bot.
-
Deje Developer Portal abierto en el explorador.
Más tarde, terminará el registro con un URL de webhook que obtendrá al crear el canal en Digital Assistant.
Paso 2: creación de un canal en Digital Assistant
-
En otra ventana o separador del explorador, abra Digital Assistant, haga clic en Canales en el menú de la izquierda y seleccione Usuarios.
-
Haga clic en Agregar canal para abrir el cuadro de diálogo Crear canal.
-
Asigne un nombre al canal.
-
Seleccione Microsoft Teams como tipo de canal.
-
Complete el campo ID de bot de Microsoft con el ID del bot de Microsoft que ha creado.
-
Complete Contraseña de bot de Microsoft (valor de secreto de cliente) con la contraseña o el valor del secreto de cliente (que no se debe confundir con el ID de secreto de cliente) generado para el bot.
-
Haga clic en Crear.
-
En la página Canales, copie el URL del webhook y péguelo en algún lugar del sistema de fácil acceso.
-
Haga clic en
y seleccione el asistente digital o la aptitud que desea asociar al canal.
-
Active el control Canal activado.
Paso 3: configuración del URL del webhook para Microsoft Teams
A continuación, debe cerrar el círculo y completar la configuración en Microsoft Teams.
-
Vuelva al separador del explorador donde tiene el portal de desarrollador de equipos abierto.
-
En el extremo izquierdo de la navegación de la página, seleccione el icono Herramientas y, a continuación, haga clic en Gestión de bots.
-
Seleccione el bot que ha creado.
- En la página del bot, seleccione el separador Configurar.
-
En el campo Dirección de punto final de bot, pegue el URL del webhook que haya obtenido al crear el canal en Digital Assistant y, a continuación, haga clic en Guardar.
Paso 4: activación de aplicaciones en el inquilino de Office 365
Lo siguiente que necesita es que el administrador de Office 365 configure el inquilino para que:
- Permita aplicaciones externas en Microsoft Teams.
- Permita la carga lateral de aplicaciones externas.
- Active las nuevas aplicaciones externas por defecto.
Para conocer los pasos concretos, consulte https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant.
Paso 5: prueba en Microsoft Teams
Una vez configurados la mensajería y el canal de Microsoft Teams, puede probar el asistente digital (o la aptitud) en Microsoft Teams. Para ello:
- En la página de la aplicación que ha creado con el portal de desarrollador de Microsoft, haga clic en el botón Vista previa en equipos.
Configuración de conexión única para canales de Microsoft Teams
Si desea que un asistente digital o una aptitud requieran la misma autenticación que haya configurado para Microsoft Teams, puede configurar la autenticación de conexión única (SSO) para ese asistente digital o aptitud en Microsoft Teams.
Una vez configurada esta autenticación de la conexión única, los usuarios podrán conectarse a Teams con sus credenciales de Azure Active Directory (Azure AD) y, a continuación, interactuar sin problemas con el asistente digital, sin tener que volver a conectarse.
Cualquier aplicación backend a la que se accede mediante el asistente digital debe soportar tokens de acceso de Azure AD directamente. Los clientes de aplicaciones en la nube (FA) basadas en Fusion que utilizan Teams también pueden tener SSO activado entre Azure AD y FA. Sin embargo, aún no es posible mantener una conversación fluida con FA desde una sesión de Teams, ya que el token de acceso de seguridad generado desde Teams no se puede utilizar directamente para comunicarse con FA. Para solucionar esta discrepancia, puede implantar una solución personalizada para un intercambio de tokens. Para obtener más información, consulta esta publicación de blog.
A continuación se muestran los pasos generales para configurar la conexión única para un canal de Microsoft Teams:
- Si aún no lo ha hecho, cree un canal de Microsoft Teams como se describe en los temas anteriores.
- Cree una aplicación Azure AD en Azure Portal.
- Actualice el registro del bot de Microsoft con los detalles de SSO.
- En Oracle Digital Assistant, registre la aplicación Azure AD como un servicio de autenticación de Microsoft Identity Platform.
- Active la autenticación en sus aptitudes mediante el servicio de autenticación que ha registrado.
Creación de una aplicación Azure AD
Para configurar SSO para una aptitud o un asistente digital en Microsoft Teams, debe crear una aplicación de Azure AD. Esta aplicación es además de la aplicación de Azure AD que ya ha creado como parte de la configuración del canal de Microsoft Teams.
Antes de comenzar, asegúrese de tener lo siguiente:
- Una cuenta de Azure con una suscripción activa.
- El ID de aplicación de Microsoft para el bot configurado con el canal de Microsoft Teams.
- Acceso de administrador al portal de Azure.
A continuación, se muestran los pasos para crear una aplicación Azure AD para conexión única:
- Cree un nuevo registro de aplicación.
- Navegue hasta https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade en el portal de Azure.
- Haga clic en Nuevo registro.
- Rellene el campo Nombre.
- En la sección Tipos de cuenta admitidos, seleccione el botón de radio Cuentas en cualquier directorio organizativo (cualquier directorio de Azure AD- Multi-inquilino) y cuentas personales de Microsoft (por ejemplo, Skype, Xbox).
- Haga clic en Registrar.
Una vez creada la aplicación, estará en la sección Visión general. Se deben crear el ID de aplicación (cliente) y el ID de directorio (inquilino) para la aplicación.
- Agregue una configuración de plataforma web:
- En la navegación izquierda, seleccione Autenticación.
- En Configuración de plataforma, haga clic en Agregar una plataforma y seleccione Web.
- Agregue un URI de redirección con el siguiente formato:
<YOUR_Oracle-Digital-Assistant_URL>/connectors/v2/callback
- Haga clic en Configurar.
- Cree un secreto de cliente:
- En la navegación izquierda, seleccione Certificados y secretos.
- Haga clic en + Nuevo secreto de cliente, rellene los campos necesarios y haga clic en Agregar.
- Copie el valor del secreto de cliente y almacénelo en un lugar seguro. Necesitará este valor más adelante.
- Configure el token:
- En la navegación izquierda, seleccione Configuración de token.
- Haga clic en + Agregar reclamación opcional.
- Para Tipo de token, seleccione Acceso.
- Seleccione estas reclamaciones:
- given_name
- upn
- Haga clic en Add.
- Seleccione el permiso de perfil Volver en el correo electrónico de Microsoft Graph, permiso de perfil (necesario para que las reclamaciones aparezcan en el token) y haga clic en Agregar.
- En la navegación izquierda, seleccione Permisos de API.
Allí puede ver que se crean tres permisos.
- Haga clic en + Agregar un permiso y agregue User.ReadBasic.All.
Necesitará esto para acceder a la información del perfil.
- Defina el URI del ID de la aplicación:
- En la navegación izquierda, seleccione Exponer una API.
- Haga clic en el campo URI de id. de aplicación.
- Actualice el valor con el formato:
api://botid-<Microsoft_App_ID_for_your_bot>
Nota
Debe ser el ID de aplicación del bot, no el de la aplicación SSO. - Haga clic en + Agregar un ámbito.
- En el panel que se abre:
- Defina
access_as_user
como el nombre de Ámbito.La parte de dominio del nombre de ámbito que se muestra justo debajo del campo de texto debe coincidir automáticamente con el URI del ID de aplicación definido en el paso anterior, con
/access_as_user
agregado al final. - Defina ¿Quién puede conceder? en Los administradores y los usuarios.
- Defina
- Rellene los campos para configurar las peticiones de datos de consentimiento de administrador y usuario con valores adecuados para el ámbito
access_as_user
.Estas son algunas sugerencias:
- Título de consentimiento del administrador: Teams puede acceder al perfil del usuario.
- Descripción del consentimiento del administrador: permite a Teams llamar a las API web de la aplicación como usuario actual.
- Título de consentimiento del usuario: Teams puede acceder a su perfil de usuario y realizar solicitudes en su nombre.
- Descripción del consentimiento del usuario: permite a Teams llamar a las API de esta aplicación con los mismos derechos que tiene
- Asegúrese de que Estado esté definido en Activado.
- En la sección Autorizaciones de aplicaciones cliente, haga clic en + Agregar una aplicación cliente.
- Introduzca los siguientes ID:
1fec8e78-bce4-4aaf-ab1b-5451cc387264
Esta es la aplicación móvil y de escritorio de Teams.
5e3ce6c0-2b1f-4285-8d4b-75ee78787346
Esta es la aplicación web de Teams.
- Actualice el manifiesto:
- En la navegación izquierda, seleccione Manifiesto.
- Defina
"acceptMappedClaims"
entrue
. - Defina
"accessTokenAcceptedVersion"
en2
. - Haga clic en Guardar.
- Otorgue permisos de administración de inquilino a la aplicación Azure AD.
- En la navegación izquierda, seleccione Visión general.
- Copie el ID de aplicación (cliente), el ID de directorio (inquilino) y el URI de ID de aplicación y guárdelo en un lugar adecuado.
- En una ventana de explorador privada, conéctese a la cuenta de administrador de Microsoft.
La dirección URL tiene el siguiente formato:
donde sustituiráhttps://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<client-id>
<tenant-id>
por el ID de directorio (inquilino) que acaba de copiar y sustituirá<client-id>
por el ID de aplicación (cliente) que acaba de copiar.
- En el cuadro de diálogo Permisos solicitados, revise y acepte los permisos.
Actualización del registro de bots con los detalles de conexión única
Actualice el bot de Microsoft con los detalles de conexión única que haya configurado:
- Abra el bot en el portal de desarrolladores de Teams y abra el Editor de manifiestos.
- Seleccione el separador Información básica.
- Desplácese hasta el campo ID de aplicación (cliente) e inserte el ID de aplicación (cliente).
- Seleccione el separador Conexión única.
- En el URI de ID de aplicación, agregue el URI de ID de aplicación que copió anteriormente.
- En la navegación de la izquierda, seleccione Publicar en organización.
Registro de la aplicación Azure AD como servicio de autenticación en Digital Assistant
Ahora registrará la aplicación Azure AD como servicio de autenticación en Oracle Digital Assistant.
-
En otra ventana o separador del explorador, abra Digital Assistant, amplíe Configuración en el menú de la izquierda y seleccione Servicios de autenticación.
- Haga clic en Agregar servicio.
- En el cuadro de diálogo Nuevo servicio de autenticación, introduzca estos valores:
- Proveedor de identidad: plataforma de identidad de Microsoft
- Nombre: nombre para identificar el servicio de autenticación.
- URL de punto final de token: URL del proveedor de identidad para solicitar tokens de acceso. Utilice:
https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/token
- Punto final de autorización: URL del proveedor de identidad para la página con la que los usuarios se autentican introduciendo su nombre de usuario y contraseña. Utilice:
https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/authorize
- Id. de cliente y secreto de cliente: ID y secreto de cliente para la aplicación Azure AD (cliente OAuth) registrados. Utilice el ID y el secreto de la aplicación.
- Ámbito:
<Application(client)_ID_for_your_bot>/access_as_user
- Reclamación del asunto: reclamación del perfil del token de acceso que se utiliza para identificar al usuario. Utilice correo electrónico.
Referencia al servicio de autenticación desde sus aptitudes
En aptitudes que necesitan autenticación SSO, incorpore el componente OAuth 2.0 Account Link en el flujo de diálogo para manejar la autenticación a través del servicio de autenticación. En ese componente, asegúrese de definir la propiedad enableSingleSignOn
en true
. (Para los flujos de diálogo basados en YAML, el componente se denomina System.OAuth2AccountLink).
Consejo:
Si no desea realizar la codificación fija del nombre del servicio de autenticación en el componente, puede crear un parámetro personalizado que se transfiera al componente. Consulte Parámetros personalizados.Capacidades admitidas
Los canales de Microsoft Teams en Digital Assistant admiten las siguientes capacidades:
- texto (tanto envío como recepción)
- imágenes (tanto envío como recepción)
- archivos (tanto envío como recepción)
- emojis (tanto envío como recepción)
- enlaces
- devoluciones
- propiedades personalizadas
- componentes del carrusel
- componentes de la lista
Si va a dirigir la aptitud a varios canales con diferentes capacidades de formato y sintaxis, puede utilizar el marcado HTML básico en los mensajes. Si lo hace, ese marcado se convertirá automáticamente al formato de rebaja de Microsoft Teams cuando el mensaje se transmita al canal. Esto es particularmente útil si está dirigiendo sus habilidades a otros canales además de Microsoft Teams. Consulte Formato de texto enriquecido en canales.
Restricciones de mensajes
Los canales de Microsoft Teams en Digital Assistant presentan las siguientes restricciones de mensajes:
- Mensajes de texto
- Longitud máxima de la etiqueta de acción de texto: 1 línea (unos 50 caracteres)
- Tipos de acciones de texto permitidas: devolución, llamada, URL
- Tarjetas horizontales
- Longitud máxima del título: 2 líneas (unos 80 caracteres)
- Longitud máxima de la descripción: 25.000 caracteres
- Longitud máxima de la etiqueta de acción de la tarjeta: 1 línea (unos 50 caracteres)
- Número máximo de tarjetas: 10
- Número máximo de acciones de tarjeta: 6. Si el número de acciones de tarjeta excede de 6, la tarjeta se duplica para representar las acciones de tarjeta restantes.
- Número mínimo de acciones de tarjeta: 0
- Número máximo de acciones de lista de tarjeta: 6
- ¿Se necesita al menos una descripción, imagen o acción?: no
- Tipos de acciones de tarjeta permitidas: devolución, llamada, URL
- Tipos de acciones de lista de tarjeta permitidas: devolución, llamada, URL
- Tarjetas verticales
- Longitud máxima del título: 2 líneas (unos 80 caracteres)
- Longitud máxima de la descripción: 25.000 caracteres
- Longitud máxima de la etiqueta de acción de la tarjeta: 1 línea (unos 50 caracteres)
- Número máximo de tarjetas: 10
- Número máximo de acciones de tarjeta: 3
- Número mínimo de acciones de tarjeta: 0
- Número máximo de acciones de lista de tarjeta: 6
- ¿Se necesita al menos una descripción, imagen o acción?: no
- Tipos de acciones de tarjeta permitidas: devolución, llamada, URL
- Tipos de acciones de lista de tarjeta permitidas: devolución, llamada, URL
- Mensajes anexos
- ¿Se admite?: sí
- Tipos de acciones permitidas: devolución, llamada, URL
- Botones de acción
- Longitud máxima de la etiqueta de acción global: 1 línea (unos 50 caracteres)
- Número máximo de acciones globales: 6
- Tipos de acciones globales permitidas: devolución, llamada, URL
Tarjetas adaptables en Microsoft Teams
Para las aptitudes que se exponen a través de los canales de Microsoft Teams en Oracle Digital Assistant, puede utilizar tarjetas adaptables.
Para ello, utilice el elemento channelCustomProperties
en un componente de respuesta común y establezca la propiedad type
en "AdaptiveCard"
.
Este elemento se puede utilizar en los siguientes niveles del componente:
- En el nivel de un elemento de tarjeta dentro de un elemento de respuesta
cards
. Permite definir una estructura de tarjeta adaptable única que se eliminará varias veces si se ha especificadoiteratorVariable
para el elemento de tarjeta. - En el nivel de un elemento de respuesta de texto, normalmente para crear una tarjeta adaptable única. (Se pueden definir varias tarjetas, pero la propiedad
iteratorVariable
no se admite aquí).
Consejo:
En el editor de flujo de diálogo (en el modo de diálogo Visual y YAML), hay una plantilla de tarjetas adaptables de Microsoft que contiene metadatos de ejemplo que puede adaptar a sus necesidades.Actualmente, Microsoft Teams no admite un carrusel con tarjetas adaptables. En términos de metadatos del componente de respuesta común, esto implica que la propiedad de diseño de tarjeta se ignora. Las tarjetas siempre se presentan en vertical porque el diseño horizontal (carrusel) no se admite.
Una segunda limitación que tener en cuenta es que, cuando un usuario pulsa un botón incluido con la tarjeta adaptable, la etiqueta del botón no se imprime como mensaje de usuario en el historial de conversaciones. Es decir, el usuario no recibe una confirmación visual del botón que ha seleccionado. Esto puede llevar a que la experiencia del usuario sea incoherente, ya que los botones que se muestran con los mensajes de texto simples o los botones que se muestran con las tarjetas de componentes de respuesta común estándar (que utilizan la tarjeta representativa de Microsoft) sí imprimen la etiqueta del botón.
Ejemplo: tarjeta adaptable en artículo de respuesta de tarjetas
Para eliminar varias tarjetas, puede utilizar iteratorVariable
con el elemento card
en un elemento de respuesta de tipo tarjetas. A continuación, se muestra un ejemplo de uso de una tarjeta adaptable para eliminar varias tarjetas de pizza:
responseItems:
- type: "cards"
headerText: "Here are our pizzas you can order today:"
cardLayout: "horizontal"
cards:
- title: "${pizzas.name}"
description: "${pizzas.description}"
imageUrl: "${pizzas.image}"
iteratorVariable: "pizzas"
actions:
- label: "Order Now"
type: "postback"
payload:
action: "order"
variables:
orderedPizza: "${pizzas.name}"
orderedPizzaImage: "${pizzas.image}"
channelCustomProperties:
- channel: "msteams"
properties:
adaptiveCard:
type: "AdaptiveCard"
version: "1.0"
fallbackText: "Adaptive card version not supported"
body:
- type: "TextBlock"
text: "${pizzas.name}"
weight: "bolder"
- type: "TextBlock"
text: "${pizzas.description}"
wrap: true
- type: "Image"
url: "${pizzas.image}"
horizontalAlignment: "center"
actions:
- type: "Action.Submit"
title: "Order"
data:
action: "order"
variables:
orderedPizza: "${pizzas.name}"
orderedPizzaImage: "${pizzas.image}"
Ejemplo: tarjeta adaptable en elemento de respuesta de texto
Puede definir una tarjeta adaptable con un elemento de respuesta de texto de la siguiente manera:
responseItems:
- type: "text"
text: "This text is replaced with adaptive card defined in custom property"
footerText: "Is that correct?"
visible:
expression: "${system.channelType=='msteams' && system.entityToResolve.value.name=='Confirmed'}"
channelCustomProperties:
- channel: "msteams"
properties:
adaptiveCard:
type: "AdaptiveCard"
version: '1.0'
fallbackText: "Adaptive card version not supported"
body:
- type: TextBlock
text: 'I have all information needed to create your expense. Just to verify my understanding, here is an overview of your expense:'
wrap: true
- type: FactSet
facts:
- title: Expense Type
value: "${expense.value.Type}"
- title: Amount
value: "${expense.value.Amount.totalCurrency}"
- title: Date
value: "${expense.value.Date.date?number_to_date}"
- title: Receipt URL
value: "${expense.value.Receipt?has_content?then(expense.value.Receipt.url,'N/A')}"
actions:
- type: Action.ShowCard
title: Edit
id: edit
card:
type: AdaptiveCard
version: '1.0'
body:
- type: TextBlock
size: Medium
weight: Bolder
text: Edit Expense
- type: TextBlock
text: Expense Type
weight: Bolder
- type: Input.ChoiceSet
choices:
- title: Metro, bus, train
value: Public transport
- title: Taxi
value: Taxi
- title: Breakfast, lunch, dinner
value: dinner
id: Type
value: "${expense.value.Type!''}"
spacing: None
- type: TextBlock
text: Amount
weight: Bolder
- type: Input.Text
id: amount
spacing: None
value: "${expense.value.Amount?has_content?then(expense.value.Amount.totalCurrency,'')}"
- type: TextBlock
text: Date
weight: Bolder
- type: Input.Date
id: Date
value: "${expense.value.Date?has_content?then(expense.value.Date.date?number_to_date,'')}"
spacing: None
actions:
- type: Action.Submit
title: Submit
id: submit
También puede definir varias tarjetas adaptables en esta propiedad personalizada. Para ello, prefije la propiedad type
con un guion (-
) para indicar una lista YAML, en lugar de una asignación:
channelCustomProperties:
- channel: "msteams"
properties:
adaptiveCard:
- type: AdaptiveCard
body: ...
- type: AdaptiveCard
body: ...
Esto puede resultar útil si necesita eliminar varias tarjetas estáticas, si bien es más habitual eliminar varias tarjetas utilizando la propiedad iteratorVariable
.
Acciones de envío
Las tarjetas adaptables tienen una acción de envío (Action.Submit
) que se puede usar para recopilar la entrada del usuario y enviarla a la aptitud.
La carga útil de la acción se define en la propiedad data
de la acción de envío. Si desea que el componente de respuesta común realice una transición después de seleccionar el botón o definir algunas variables, puede utilizar las propiedades estándar action
y variables
:
actions:
- type: "Action.Submit"
title: "Order"
data:
action: "order"
variables:
orderedPizza: "${pizzas.name}"
orderedPizzaImage: "${pizzas.image}"
Si utiliza campos de entrada en la tarjeta, el nombre y el valor de estos campos se agregarán como pares clave-valor al objeto JSON data
. En el ejemplo anterior, con la tarjeta Editar gasto, se incluyen tres campos para modificar el tipo de gasto, el importe y la fecha. Cuando el usuario pulsa el botón Enviar en este caso, se envía un objeto JSON como el siguiente:
{
"Type" : "Taxi",
"Amount" : "10.0 dollar"
"Date" : "2019-09-02"
}
El componente Respuesta Común no sabe cómo procesar esta información, ya que no sigue la estructura de carga útil común con las propiedades action
y variables
. Para resolver este problema, tiene estas opciones:
-
Convertir la carga útil de JSON en una cadena que luego se pareará con entidades. Si se encuentra alguna coincidencia, se actualizará el juego de variables con el componente con el valor de entidad o los valores de entidad correspondientes (en el caso de una entidad de bolsa compuesta).
Para configurar esta opción, agregue la propiedad booleana
system.convertToString
a la propiedaddata
de la acción de envío:actions: - type: Action.Submit title: Submit id: submit data: system.convertToString: true
-
Hacer que la aptitud actualice las variables con el mismo nombre que los campos de entrada. En el ejemplo anterior, se actualizarían las variables
"Type"
,"Amount"
y"Date"
.Para configurar esta opción, agregue la propiedad booleana
system.setVariables
a la propiedaddata
de la acción de envío:actions: - type: Action.Submit title: Submit id: submit data: system.setVariables: true
Si no configura ninguna de estas opciones, los valores enviados se ignorarán.
Si utiliza un componente de respuesta común con una entidad de bolsa compuesta, normalmente utilizará la primera opción, que rellenará todas las entidades coincidentes en la bolsa en función de la carga útil de JSON de la cadena.
Debe definir la propiedad
processUserMessage
del componente en true
para que estas acciones de envío funcionen.
Eco de texto del botón seleccionado en tarjeta adaptable
Cuando un usuario selecciona un botón en una tarjeta adaptable, la conversación no se actualiza para mostrar que el usuario ha seleccionado dicha opción a menos que incluya una acción messageBack
para la tarjeta
Para configurar una acción messageBack
, consulte https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions#adaptive-cards-with-messageback-action.
Desactivación de botones y campos en tarjetas adaptables
Aunque no puede desactivar técnicamente los botones y campos de las tarjetas adaptables, puede crear un efecto similar sustituyendo la tarjeta cuando se llama a una acción de envío. Para ello, utilice la propiedad booleana replaceMessage
específica de Microsoft Teams en los componentes de Common Response.
Para permitir que la tarjeta se vuelva a representar de esta forma, agregue esta propiedad en la sección channelCustomProperties
del componente de respuesta personalizado:
...
- type: "text"
text: "This text is replaced with the adaptive card defined in custom property"
channelCustomProperties:
- channel: "msteams"
properties:
replaceMessage: "true"
adaptiveCard:
...
También puede utilizar una expresión de Apache FreeMarker para definir el valor de la propiedad.
Consejos para crear definiciones de tarjetas adaptables
El esquema JSON de las tarjetas adaptables es relativamente complejo, ya que admite muchas construcciones diferentes. Por lo tanto, es probable que se produzcan errores cuando se intenta definir el contenido de la tarjeta adaptable directamente dentro de un componente de respuesta común. Es posible que le resulte más sencillo usar el siguiente proceso para crear tarjetas adaptables:
- Con las herramientas visuales del Diseñador de tarjetas adaptables de Microsoft, cree la definición de la tarjeta adaptable.
- Haga clic en Copiar JSON de tarjeta para obtener la definición en formato JSON.
- Utilice un conversor en línea (como https://jsonformatter.org/json-to-yaml) para convertir la definición a YAML.
- Copie el resultado en un editor de texto e inserte el sangrado necesario en el lugar donde aparecerá en la definición del flujo de diálogo.
- Pegue el texto resultante en el flujo de diálogo.
Para mantenerse actualizado sobre la versión de tarjetas adaptables soportadas por Teams, consulte https://docs.microsoft.com/en-us/adaptive-cards/resources/partners. Puede visitar https://adaptivecards.io/explorer/ para obtener una lista de todos los elementos y propiedades, junto con la versión en la que se introdujeron.
Tenga en cuenta que el diseñador de tarjetas adaptables no comprueba la combinación de los elementos utilizados y el número de versión de las tarjetas adaptables. Por ejemplo, el elemento ActionSet
se introdujo en la versión 1.2, pero el diseñador no le impide agregar este elemento, aunque haya especificado 1.0 como número de versión en el diseñador.
Si quiere utilizar acciones con la versión 1.0, puede utilizar la propiedad actions
bajo la propiedad body
. Este elemento actions
no se puede agregar utilizando el diseñador visual, por lo que deberá hacerlo manualmente.
Desactivación del mensaje de bienvenida para un asistente digital
Cuando un usuario se conecta a un asistente digital a través de un canal de Microsoft Teams, se envía un mensaje interno al asistente digital para iniciar una conversación. Por defecto, ese mensaje es la palabra "ayuda", que, a continuación, dispara la intención del sistema help
del asistente digital, lo que lleva a la visualización de un mensaje de bienvenida y tarjetas para las aptitudes del asistente digital.
Para desactivar este comportamiento, cambie la propiedad Internal Welcome Message
a un valor distinto de "help". Puede cambiar el valor de esa propiedad en el grupo de recursos del asistente digital.
Para cambiar el mensaje interno definido en el asistente digital cuando el usuario se conecta con un canal de Teams:
- Haga clic en
para abrir el menú lateral, seleccione Desarrollo > Asistentes digitales y abra el asistente digital.
- En la navegación izquierda del asistente digital, haga clic en
, y seleccione el separador Configuración.
- En el campo Filtro, escriba
internal
para reducir rápidamente la lista de claves de grupos de recursos. - Seleccione la clave Otro - internalWelcomeMessage.
- Pase el mouse sobre el valor de la clave y seleccione el icono
que aparece.
- Sustituya el valor por el que desea utilizar y haga clic en Actualizar entrada.
Si el asistente digital tiene una versión de plataforma anterior a la 21.04, las claves de grupo de recursos no se definen automáticamente para las propiedades de configuración. En ese caso, puede que solo desee actualizar el valor de la propiedad en la página Configuración de los asistentes digitales (que puede abrir haciendo clic en

Activar el mensaje de bienvenida para una aptitud
Por defecto, cuando un usuario se conecta directamente a una aptitud independiente a través de un canal de Microsoft Teams, no se envía ningún mensaje de bienvenida al usuario. Sin embargo, si configura la propiedad Welcome State de la aptitud, la aptitud utilizará ese estado para mostrar un mensaje cuando el usuario se conecte.
- Haga clic en
para abrir el menú lateral, seleccione Desarrollo > Aptitudes y abra la aptitud.
- En la navegación izquierda de la aptitud, haga clic en
y seleccione el separador Digital Assistant.
- En el campo Estado de bienvenida, introduzca el nombre del estado en el que desea mostrar el mensaje de bienvenida.
El uso de la propiedad Estado de bienvenida de esta forma para una aptitud independiente solo funciona para canales de Microsoft Teams. Para otros canales, esta propiedad se ignora en aptitudes independientes.