Crear vínculos profundos a contenido y características en Microsoft Teams

  • Tiempo de lectura: 8 minutos

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

  • Navegar por el 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 pestaña para que el usuario pueda ver más detalles sobre la actividad.
  • La aplicación automatiza o simplifica determinadas tareas del usuario, como crear un chat o programar una reunión, mediante la rellenar previamente los vínculos profundos con los parámetros necesarios. Esto evita la necesidad de que los usuarios escriban manualmente información.

Nota

Un vínculo profundo inicia el explorador primero antes de navegar a contenido e información de la siguiente manera:

Pestaña:
✔ navega directamente a la dirección URL de deeplink.

Bot:
✔ Deeplink en el cuerpo de la tarjeta: se abre primero en el explorador.
✔ deeplink agregado a la acción OpenURL en la tarjeta adaptable: navega directamente a la dirección URL de deeplink.
✔ texto de markdown de hipervínculo en la tarjeta: se abre primero en el explorador.

Chat:
✔ markdown de hipervínculo de mensaje de texto: navega directamente a la dirección URL de vínculo profundo.
✔ vínculo pegada en la conversación de chat general: navega directamente a la dirección URL de deeplink.

Vinculación profunda a la pestaña

Puede crear vínculos profundos a entidades en Teams. Normalmente, esto se usa para crear vínculos que navegan a contenido e información dentro de la pestaña. Por ejemplo, si la pestaña contiene una lista de tareas, los miembros del equipo pueden crear y compartir vínculos a tareas individuales. Cuando se hace clic en él, el vínculo se desplaza a la pestaña que se centra en el elemento específico. Para implementar esto, agregue una acción de "copiar vínculo" a cada elemento, de la forma que mejor se adapte a su interfaz de usuario. Cuando el usuario realiza esta acción, se llama para mostrar un cuadro de diálogo que contiene un vínculo que el usuario shareDeepLink() puede copiar en el Portapapeles. Al realizar esta llamada, también pasas un identificador para el elemento, que vuelves a obtener 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, con el formato especificado más adelante en este tema. Es posible que desee usarlas en mensajes de bots y conectores que informan a los usuarios sobre los cambios en la pestaña o en los elementos dentro de ella.

Nota

Esto es diferente de los vínculos proporcionados por el elemento de menú Copiar vínculo a pestaña, que simplemente genera un vínculo profundo que apunta a esta pestaña.

Nota

Actualmente, shareDeepLink no funciona en plataformas móviles.

Para mostrar un cuadro de diálogo que contiene un vínculo profundo a un elemento dentro de la pestaña, llame microsoftTeams.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 vincula profundamente
  • subEntityLabel Una etiqueta para el elemento que se usará para mostrar el vínculo profundo
  • 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

Nota

Las pestañas personales tienen un ámbito, mientras que las pestañas de canal y personal grupo usan team o group ámbitos. Los dos tipos de pestaña tienen una sintaxis ligeramente diferente, ya que solo la ficha configurable tiene una channel propiedad asociada a su objeto de contexto. Consulta la referencia del manifiesto para obtener más información sobre los ámbitos de pestaña.

Nota

Los vínculos profundos solo funcionan correctamente si la pestaña se configuró con la biblioteca v0.4 o posterior y, por ello, tiene un identificador de entidad. Los vínculos profundos a pestañas sin identificadores de entidad siguen navegando a la pestaña, pero no pueden proporcionar el identificador de la sub entity a la pestaña.

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

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

Nota

Si el bot envía un mensaje que contiene un vínculo profundo, se abre una nueva pestaña del explorador cuando el usuario TextBlock selecciona el vínculo. Esto sucede en Chrome y en la aplicación de escritorio de Microsoft Teams, ambos en Linux. Si el bot envía la misma dirección URL de vínculo profundo a una , la pestaña Teams se abre en la pestaña del explorador actual cuando el usuario hace clic Action.OpenUrl en el vínculo. No se abre ninguna pestaña nueva del explorador.

Los parámetros de consulta son:

  • appId El identificador del manifiesto; por ejemplo, "fe4a8eba-2a31-4737-8e33-e5fae6fee194"
  • entityId El identificador del elemento de la pestaña, que proporcionó al configurar la pestaña; por ejemplo, "tasklist123"
  • entityWebUrlo 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 subEntityWebUrl   ejemplo, " https://tasklist.example.com/123 " o https://tasklist.example.com/list123/task456 " "
  • entityLabelo una etiqueta para el elemento de la pestaña, que se usará al mostrar el vínculo profundo; por ejemplo, "Lista de tareas subEntityLabel   123" o "Tarea 456"
  • context Un objeto JSON que contiene los siguientes campos:
    • subEntityId Un identificador para el elemento dentro de la pestaña; por ejemplo, "task456"
    • channelId El identificador de canal de Microsoft Teams (disponible en el contexto depestaña; por ejemplo, "19:cbe3683f25094106b826c9cada3afbe0@thread.skype". Esta propiedad solo está disponible en pestañas configurables con un ámbito de "equipo". No está disponible en pestañas estáticas, que tienen un ámbito de "personal".

Ejemplos:

  • Vínculo a una pestaña configurable: 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"}

Importante

Asegúrese de que todos los parámetros de consulta estén codificados correctamente como URI. Por razones de legibilidad, los ejemplos anteriores no lo son, pero debe hacerlo. Con el último ejemplo:

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;

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

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

Vinculación profunda desde la pestaña

Puede vincular en profundidad al contenido de Teams desde su pestaña. Esto es útil si la pestaña necesita vincularse a otro contenido de 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, debes llamar a:

microsoftTeams.executeDeepLink(/*deepLink*/);

Esto te llevará a la dirección URL correcta o desencadenará una acción del cliente, como abrir un cuadro de diálogo de programación o instalación de la aplicación. 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 especificando el conjunto de participantes. Si no existe un chat con los participantes especificados, el vínculo navegará al usuario a un nuevo chat vacío. Los chats nuevos se crearán en estado borrador hasta que el usuario envíe el primer mensaje. Opcionalmente, puede especificar el nombre del chat (si aún no existe), junto con el texto que debe insertarse en el cuadro de redacción del usuario. Puede pensar en esta característica como un acceso directo para que el usuario tome la acción manual de navegar al chat o crearlo y, a continuación, escribir el mensaje.

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

Use este formato para un vínculo profundo que puede usar en un bot, conector o tarjeta de 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:

  • users: la lista separada por comas de los id. de usuario que representan a los participantes del chat. El usuario que realiza la acción siempre se incluye como participante. Actualmente, el campo Id. de usuario solo admite el userPrincipalName de Azure AD (normalmente una dirección de correo electrónico).
  • topicName: un campo opcional para el nombre para mostrar del 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: campo opcional para el texto del mensaje que desea insertar en el cuadro de redacción del usuario actual mientras el chat está en un estado de borrador.

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

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

Nota

Esta característica se encuentra actualmente en versión preliminar para desarrolladores.

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

Use este formato para un vínculo profundo que puede usar en un bot, conector o tarjeta de 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:

  • attendees: la lista opcional separada por comas de los id. de usuario que representan a los asistentes de la reunión. El usuario que realiza la acción es el organizador de la reunión. Actualmente, el campo Id. de usuario solo admite el 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 8601largo, por ejemplo "2018-03-12T23:55:25+02:00".
  • endTime: 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 de 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 UTC (zonas horarias).

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