Vínculo profundo a un flujo de trabajo en Teams

Puede crear un vínculo profundo para realizar una tarea específica en Teams, como crear un nuevo chat, abrir un cuadro de diálogo de programación y navegar a la llamada de audio y vídeo.

En este artículo, aprenderá a crear un vínculo profundo:

• Para iniciar un nuevo chat
• Para abrir un cuadro de diálogo de programación de reuniones
• Para iniciar una llamada de audio y vídeo
• Para compartir el contenido que se va a realizar en las reuniones
• Al panel lateral de la reunión
• Para unirse a una reunión

Vínculo profundo para iniciar un nuevo chat

Las aplicaciones pueden iniciar un nuevo chat con una lista de usuarios y proporcionar información adicional, como el nombre del chat y el borrador de mensaje, con el siguiente formato:

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: lista separada por comas de identificadores de usuario que representan a los participantes del chat. El usuario que realiza la acción siempre se incluye como participante. El campo id. de usuario admite el Microsoft Entra UserPrincipalName, como solo una dirección de correo electrónico.
• topicName: un campo opcional para el nombre para mostrar del chat si un chat tiene tres o más usuarios. Si no se especifica este campo, el nombre para mostrar del chat se basa en los nombres de los participantes.
• message: un campo opcional para el texto del mensaje que quiere 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, especifique el vínculo profundo como destino de dirección URL en el botón de la tarjeta o pulse la acción a través del openUrl tipo de acción. Las aplicaciones también pueden usar la biblioteca cliente JavaScript de Teams (TeamsJS) v.2.0 o posterior para crearla sin tener que preparar manualmente el vínculo profundo. En el ejemplo siguiente se usa TeamsJS para comprobar si se admite la funcionalidad de chat:

if(chat.isSupported()) {
    const chatPromise = chat.openGroupChat({ users: ["joe@contoso.com","bob@contoso.com"], topic: "Prep For Meeting Tomorrow", message: "Hi folks kicking off chat about our meeting tomorrow"});
    chatPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Vínculo profundo para abrir un cuadro de diálogo de programación de reuniones

Puede crear un vínculo profundo en las aplicaciones de Teams para abrir un cuadro de diálogo de programación de reuniones y proporcionar información, como el título de la reunión y los participantes mediante los métodos siguientes:

• Configuración manual del vínculo profundo para abrir un cuadro de diálogo de programación de reuniones
• Configuración del vínculo profundo mediante la biblioteca TeamsJS para abrir un cuadro de diálogo de programación de reuniones

Aunque se recomienda el uso de API con tipo de TeamsJS, es posible crear manualmente vínculos profundos al cuadro de diálogo de programación integrado de Teams.

Configuración manual del vínculo profundo para abrir un cuadro de diálogo de programación de reuniones

Use el siguiente formato para configurar un vínculo profundo que puede usar en un bot, conector o tarjeta de extensión de mensaje:

https://teams.microsoft.com/l/meeting/new?subject=<meeting subject>&startTime=<date>&endTime=<date>&content=<content>&attendees=<user1>,<user2>,<user3>,...

Los parámetros de consulta son:

• attendees: una lista opcional separada por comas de identificadores 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. El campo id. de usuario solo admite el Microsoft Entra UserPrincipalName, normalmente una dirección de correo electrónico.
• startTime: parámetro opcional para la hora de inicio del evento. La hora de inicio debe estar en formato ISO 8601 largo, por ejemplo , 2018-03-12T23:55:25+02:00.
• endTime: parámetro opcional para la hora de finalización del evento, también en formato ISO 8601.
• subject: parámetro opcional para el asunto de la reunión.
• content: parámetro opcional para el campo de detalles de la reunión.

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

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​​​​​​​​​​​​​​

Configuración del vínculo profundo mediante la biblioteca TeamsJS para abrir un cuadro de diálogo de programación de reuniones

También puede usar TeamsJS v.2.0 o posterior en la aplicación teams para abrir el cuadro de diálogo de programación de reuniones sin tener que preparar manualmente el vínculo. Para abrir el cuadro de diálogo de programación en Teams, debe seguir usando el método original basado en direcciones URL de vínculo profundo, ya que Teams aún no admite la funcionalidad de calendario:

// Open a scheduling dialog from your tab
if(calendar.isSupported()) {
   const calendarPromise = calendar.composeMeeting({
      attendees: ["joe@contoso.com", "bob@contoso.com"],
      content: "test content",
      endTime: "2018-10-24T10:30:00-07:00",
      startTime: "2018-10-24T10:00:00-07:00",
      subject: "test subject"});
   calendarPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

// 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​​​​​​​​​​​​​​");

Para obtener más información sobre cómo trabajar con el calendario, consulte el espacio de nombres del calendario en la documentación de referencia de la API.

Vínculo profundo para iniciar una llamada de audio y vídeo con los usuarios

Puede configurar las aplicaciones de Teams para preparar un vínculo profundo para que los usuarios inicien una llamada uno a uno, una llamada grupal o una videollamada. Puede invocar solo audio o audio-vídeo a un único usuario o grupo de usuarios especificando el tipo de llamada y los participantes. Antes de que Teams coloque la llamada, el cliente solicita una confirmación. Si hay una llamada de grupo, puede llamar a un conjunto de usuarios VoIP y RTC en la misma invocación de vínculo profundo.

En una videollamada, el cliente de Teams solicita confirmación antes de activar el vídeo del autor de la llamada para la llamada. El receptor de la llamada tiene la opción de responder solo a través de audio o con audio y vídeo, a través de la ventana de notificación de llamadas de Teams.

Puede configurar vínculos profundos de una de las dos maneras siguientes:

• Configuración manual del vínculo profundo para iniciar la llamada de audio y vídeo con los usuarios
• Configuración del vínculo profundo mediante la biblioteca TeamsJS para iniciar una llamada de audio y vídeo con los usuarios

Configuración manual del vínculo profundo para iniciar la llamada de audio y vídeo con los usuarios

Aunque se recomienda el uso de las API con tipo de TeamsJS v.2.0 o posterior, también puede usar un vínculo profundo configurado manualmente para iniciar una llamada. Consulte los siguientes formatos:

Estos son los parámetros de consulta:

• users: lista separada por comas de identificadores de usuario que representan a los participantes de la llamada. El campo id. de usuario admite el Microsoft Entra UserPrincipalName, normalmente una dirección de correo electrónico o, en una llamada RTC, admite una MRI RTC 4:<phonenumber>.
• withVideo: parámetro opcional que puede usar para realizar una videollamada. Al establecer este parámetro, solo se activa la cámara del autor de la llamada. El receptor de la llamada tiene la opción de responder a través de un audio o una llamada de audio y vídeo a través de la ventana de notificación de llamadas de Teams.

Configuración del vínculo profundo mediante la biblioteca TeamsJS para iniciar una llamada de audio y vídeo con los usuarios

Las aplicaciones también pueden usar TeamsJS v.2.0 o posterior para iniciar llamadas sin tener que preparar manualmente estos vínculos profundos. En el código siguiente se muestra cómo usar TeamsJS para iniciar una llamada:

if(call.isSupported()) {
    const callPromise = call.startCall({ targets: ["joe@contoso.com","bob@contoso.com","4:9876543210"], requestedModalities: [call.CallModalities.Audio], source: "demoApp"});
    callPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Vínculo profundo para compartir contenido para realizar una fase en las reuniones

Para agregar un vínculo profundo para compartir contenido en el escenario, debe tener un contexto de aplicación. El contexto de la aplicación permite al cliente de Teams capturar el manifiesto de la aplicación y comprobar si es posible el uso compartido en el escenario. A continuación se muestra un ejemplo de contexto de aplicación:

{ "appSharingUrl" : "https://teams.microsoft.com/extensibility-apps/meetingapis/view", "appId": "9ec80a73-1d41-4bcb-8190-4b9eA9e29fbb" , "useMeetNow": false }

Los parámetros de consulta para el contexto de la aplicación son:

• appID: es el identificador que se puede obtener del manifiesto de la aplicación.
• appSharingUrl: la dirección URL, que debe compartirse en el escenario, debe ser un dominio válido definido en el manifiesto de la aplicación. Si la dirección URL no es un dominio válido, aparece un cuadro de diálogo de error para proporcionar al usuario una descripción del error.
• useMeetNow: incluye un parámetro booleano que puede ser true o false.

  • True: cuando el useMeetNow valor es true y no hay ninguna reunión en curso, se iniciará una nueva reunión meet now. Cuando haya una reunión en curso, se omitirá este valor.

  • False: el valor predeterminado de useMeetNow es false, lo que significa que cuando se comparte un vínculo profundo en la fase y no hay ninguna reunión en curso, aparecerá un elemento emergente de calendario. Sin embargo, puede compartir directamente durante una reunión.

Asegúrese de que todos los parámetros de consulta están correctamente codificados mediante URI y que el contexto de la aplicación debe codificarse dos veces en la dirección URL final. A continuación se muestra un ejemplo:

const appContext= JSON.stringify({ 
  "appSharingUrl" : "https://teams.microsoft.com/extensibility-apps/meetingapis/view",
  "appId": "9cc80a93-1d41-4bcb-8170-4b9ec9e29fbb",
  "useMeetNow": false
});
const encodedContext = encodeURIComponent(appContext).replace(/'/g,"%27").replace(/"/g,"%22");
const encodedAppContext = encodeURIComponent(encodedContext).replace(/'/g,"%27").replace(/"/g,"%22");

Se puede iniciar un vínculo profundo desde la web de Teams o desde el cliente de escritorio o móvil de Teams.

Los parámetros de consulta son:

• deepLinkId: cualquier identificador usado para la correlación de telemetría.
• fqdn: fqdn es un parámetro opcional, que se puede usar para cambiar a un entorno adecuado de una reunión para compartir una aplicación en el escenario. Admite escenarios en los que se produce un recurso compartido de aplicaciones específico en un entorno determinado. El valor predeterminado de es dirección URL de fqdn empresa y los valores posibles son Teams.live.com para Teams for Life, teams.microsoft.como teams.microsoft.us.

Puede generar un vínculo profundo para compartir la aplicación para realizar la fase e iniciar o unirse a una reunión.

Vínculo profundo al panel lateral de la reunión

Puede generar un vínculo profundo al panel lateral de la reunión en una reunión. Use el siguiente formato para un vínculo profundo al panel lateral de la reunión:

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

Ejemplo:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

De forma predeterminada, se abre un vínculo profundo en un panel lateral de la reunión. Para abrir un vínculo profundo directamente en una aplicación en lugar del panel lateral de la reunión, agregue openInMeeting=false el formato de vínculo profundo:

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

Para obtener más información, consulte vínculo profundo a una pestaña.

El vínculo profundo no se abre en el panel lateral de la reunión en los siguientes escenarios:

• No hay ninguna reunión activa.
• La aplicación no tiene sidePanel el contexto declarado en el manifiesto de la aplicación.
• openInMeeting se establece false en en el vínculo profundo.
• El vínculo profundo se selecciona fuera de la ventana o componente de la reunión.
• El vínculo profundo no coincide con la reunión actual, como un vínculo profundo creado en otra reunión.

Vínculo profundo para unirse a una reunión

La aplicación Teams puede leer la dirección URL para unirse a una dirección URL de reunión a través de graph API. Este vínculo profundo abre la interfaz de usuario para que el usuario se una a la reunión. Para obtener más información, vea Obtener onlineMeeting y obtener detalles de la reunión.

Ejemplo de código