Crear vínculos profundos para el contenido y las características en Microsoft Teams

• 04/02/2020
• Tiempo de lectura: 8 minutos

Puede crear vínculos a información y características dentro del cliente de Microsoft Teams. Ejemplos de dónde puede resultar útil esto:

• Navegar al usuario al contenido dentro de una de las pestañas de la aplicación. Por ejemplo, la aplicación puede tener un bot que envía mensajes que notifican al usuario de una actividad importante. Cuando el usuario pulsa en la notificación, el vínculo profundo navega a la ficha para que el usuario pueda ver más detalles sobre la actividad.
• La aplicación automatiza o simplifica determinadas tareas de usuario, como la creación de un chat o la programación de una reunión, rellenando previamente los vínculos profundos con los parámetros necesarios. Esto evita la necesidad de que los usuarios escriban información manualmente.

Vínculo profundo a su pestaña

Puede crear vínculos profundos a entidades en Microsoft Teams. Normalmente, se usa para crear vínculos que naveguen al contenido y a la información dentro de la pestaña. Por ejemplo, si la ficha contiene una lista de tareas, los miembros del equipo pueden crear y compartir vínculos a tareas individuales. Cuando se hace clic en el vínculo, se desplaza a la ficha que se centra en el elemento específico. Para implementar esto, se agrega una acción "Copiar vínculo" a cada elemento, de la manera que mejor se adapte a la interfaz de usuario. Cuando el usuario realiza esta acción, llama shareDeepLink() a para mostrar un cuadro de diálogo que contiene un vínculo que el usuario puede copiar en el portapapeles. Al realizar esta llamada, también pasa un identificador para el elemento, que se obtiene en el contexto cuando se sigue el vínculo y se vuelve a cargar la pestaña.

Como alternativa, también puede generar vínculos profundos mediante programación, usando el formato especificado más adelante en este tema. Es posible que desee usarlos en mensajes de robot y conectores que informen a los usuarios sobre los cambios en la pestaña, o los elementos que contiene.

Mostrar un vínculo profundo a un elemento dentro de la pestaña

Para mostrar un cuadro de diálogo que contenga un vínculo profundo a un elemento dentro de la pestaña, llame amicrosoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })

Proporcione estos campos:

• subEntityId Un identificador único para el elemento dentro de la pestaña al que se va a vincular en profundidad
• subEntityLabel Etiqueta del elemento que se va a usar para mostrar el vínculo en profundidad.
• subEntityWebUrl Un campo opcional con una dirección URL de reserva para usar si el cliente no admite la representación de la pestaña

Creación de un vínculo profundo a su pestaña

Use este formato para un vínculo profundo que puede usar en una tarjeta de bot, conector o extensión de mensajería:

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>

Los parámetros de consulta son los siguientes:

• appId El identificador del manifiesto; por ejemplo, "fe4a8eba-2a31-4737-8E33-e5fae6fee194"
• entityId IDENTIFICADOR del elemento de la ficha, que se ha proporcionado al configurar la pestaña; por ejemplo, "tasklist123"
• entityWebUrlo subEntityWebUrl  un campo opcional con una dirección URL de reserva para usar si el cliente no admite la representación de la pestaña; por ejemplo, "https://tasklist.example.com/123" o "https://tasklist.example.com/list123/task456"
• entityLabelo subEntityLabel  una etiqueta para el elemento de la pestaña, para utilizar al mostrar el vínculo profundo; por ejemplo, "lista de tareas 123" o "tarea 456"
• context Un objeto JSON que contiene los siguientes campos:
  • subEntityId IDENTIFICADOR del elemento dentro de la pestaña; por ejemplo, "task456"
  • channelId El identificador de canal de Microsoft Teams (disponible desde el contextode la pestaña; por ejemplo, "19: cbe3683f25094106b826c9cada3afbe0@thread. Skype". Esta propiedad solo está disponible en pestañas configurables con un ámbito de "Team". No está disponible en las pestañas estáticas, que tienen un ámbito de "personal".

Ejemplos:

• Vincular a una pestaña configurable en sí:https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123&context={"channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}
• Vínculo a un elemento de tarea dentro de la pestaña configurable:https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456","channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}
• Vínculo a una pestaña estática en sí:https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123
• Vínculo a un elemento de tarea dentro de la pestaña estática:https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456"}

var encodedWebUrl = encodeURI('https://tasklist.example.com/123/456&label=Task 456');
var encodedContext = encodeURI('{"subEntityId": "task456"}');
var taskItemUrl = 'https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=' + encodedWebUrl + '&context=' + encodedContext;

Utilizar un vínculo profundo desde una pestaña

Cuando se navega a un vínculo profundo, Microsoft Teams simplemente se desplaza a la pestaña y proporciona un mecanismo a través de la biblioteca de JavaScript de Microsoft Teams para recuperar el identificador de subentidad (si existe).

La microsoftTeams.getContext llamada devuelve un contexto que incluye el subEntityId campo si la pestaña se navegó a través de un vínculo profundo.

Vínculo profundo desde la pestaña

Puede hacer un vínculo profundo a contenido en Teams desde la pestaña. Esto es útil si la pestaña tiene que vincular a otro contenido de Microsoft Teams, como un canal, un mensaje, otra pestaña o incluso para abrir un cuadro de diálogo de programación. Para desencadenar un vínculo profundo desde la pestaña debe llamar a:

microsoftTeams.executeDeepLink(/*deepLink*/);

Esto le permitirá navegar hasta la dirección URL correcta o desencadenar una acción de cliente como abrir un cuadro de diálogo de programación o instalación de aplicaciones. Ejemplo:

// Open a scheduling dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/meeting/new?subject=test%20subject&attendees=joe@contoso.com,bob@contoso.com&startTime=10%2F24%2F2018%2010%3A30%3A00&endTime=10%2F24%2F2018%2010%3A30%3A00&content=test%3Acontent");

// Open an app install dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/app/f46ad259-0fe5-4f12-872d-c737b174bcb4");

Vinculación profunda a un chat

Puede crear vínculos profundos a chats privados entre usuarios si especifica el conjunto de participantes. Si no existe un chat con los participantes especificados, el vínculo navegará al usuario hacia un chat nuevo vacío. Los chats nuevos se crearán en el estado de borrador hasta que el usuario envíe el primer mensaje. Opcionalmente, puede especificar el nombre del chat (si todavía no existe), junto con el texto que debe insertarse en el cuadro de redacción del usuario. Esta característica se puede considerar como un método abreviado para que el usuario realice la acción manual de navegar o crear el chat y, a continuación, escribir el mensaje.

Como ejemplo de uso de ejemplo, si va a devolver un perfil de usuario de Office 365 de su bot como tarjeta, este vínculo profundo puede permitir al usuario chatear fácilmente con esa persona.

Creación de un vínculo profundo a un chat

Use este formato para un vínculo profundo que puede usar en una tarjeta de bot, conector o extensión de mensajería:

https://teams.microsoft.com/l/chat/0/0?users=<user1>,<user2>,...&topicName=<chat name>&message=<precanned text>

Ejemplo: https://teams.microsoft.com/l/chat/0/0?users=joe@contoso.com,bob@contoso.com&topicName=Prep%20For%20Meeting%20Tomorrow&message=Hi%20folks%2C%20kicking%20off%20a%20chat%20about%20our%20meeting%20tomorrow

Los parámetros de consulta son los siguientes:

• users La lista de identificadores de usuario separados por comas que representan los participantes del chat. El usuario que realiza la acción siempre se incluye como un participante. Actualmente, el campo de identificador de usuario solo admite la UserPrincipalName de Azure AD (normalmente una dirección de correo electrónico).
• topicName Un campo opcional para el nombre para mostrar de un chat, en el caso de un chat con 3 o más usuarios. Si no se especifica este campo, el nombre para mostrar del chat se basará en los nombres de los participantes.
• message Un campo opcional para el texto del mensaje que desea insertar en el cuadro de redacción del usuario actual mientras el chat está en estado de borrador.

Para usar este vínculo profundo con el bot, puede especificarlo como destino de dirección URL en el botón de la tarjeta o en acción de openUrl puntear a través del tipo de acción.

Vinculación al cuadro de diálogo programación

Puede crear vínculos profundos al cuadro de diálogo de programación integrada del cliente de Microsoft Teams. Esto es especialmente útil si la aplicación ayuda al usuario a completar tareas relacionadas con el calendario o la programación.

Generar un vínculo profundo al cuadro de diálogo de programación

Use este formato para un vínculo profundo que puede usar en una tarjeta de bot, conector o extensión de mensajería:https://teams.microsoft.com/l/meeting/new?subject=<meeting subject>&startTime=<date>&endTime=<date>&content=<content>&attendees=<user1>,<user2>,<user3>,...

Ejemplo: https://teams.microsoft.com/l/meeting/new?subject=test%20subject&attendees=joe@contoso.com,bob@contoso.com&startTime=10%2F24%2F2018%2010%3A30%3A00&endTime=10%2F24%2F2018%2010%3A30%3A00&content=test%3Acontent

Los parámetros de consulta son los siguientes:

• attendees La lista opcional de identificadores de usuario separados por comas que representa a los asistentes de la reunión. El usuario que realiza la acción es el organizador de la reunión. Actualmente, el campo de identificador de usuario solo admite la UserPrincipalName de Azure AD (normalmente una dirección de correo electrónico).
• startTime La hora de inicio opcional del evento. Debe estar en formato ISO 8601 largo, por ejemplo, "2018-03-12T23:55:25 + 02:00".
• endTime La hora de finalización opcional del evento, también en formato ISO 8601.
• subject Un campo opcional para el asunto de la reunión.
• content Un campo opcional para el campo detalles de la reunión.

Actualmente, no se admite la especificación de la ubicación. Al generar las horas de inicio y finalización, asegúrese de especificar el desplazamiento de UTC (zonas horarias).

Para usar este vínculo profundo con el bot, puede especificarlo como destino de dirección URL en el botón de la tarjeta o en acción de openUrl puntear a través del tipo de acción.