Vínculo profundo al chat de Teams

  • Artículo

Puede crear un vínculo profundo a un chat de Teams, como iniciar un nuevo chat, ir a una conversación de canal y acceder a un archivo dentro de un canal.

En este artículo, aprenderá a crear:

Puede navegar a o crear chats privados entre usuarios con la biblioteca cliente JavaScript de Microsoft Teams (TeamsJS) especificando el conjunto de participantes. Si no existe un chat con los participantes especificados, el vínculo lleva al usuario a un nuevo chat vacío.

Cuando un usuario crea un nuevo chat mediante un vínculo profundo, Teams crea el nuevo chat en estado borrador hasta que el usuario envía el primer mensaje. También puede proporcionar el nombre del chat si aún no existe, junto con el texto que se debe insertar en el cuadro de redacción del usuario. Considere este acceso directo para que el usuario realice la acción manual de navegar o crear el chat y, a continuación, redacte el mensaje.

Como ejemplo de caso de uso, si está recuperando una información de perfil de usuario de Microsoft 365 del bot como una tarjeta, este vínculo profundo puede permitir que el usuario de la aplicación chatee fácilmente con esa persona.

Puede configurar vínculos profundos para iniciar un nuevo chat de una de las dos maneras siguientes:

Aunque se recomienda el uso de las API tipeadas, también puede usar el siguiente formato para un vínculo profundo creado manualmente que puede usar en un bot, conector o tarjeta de extensión de mensaje:

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

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.

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. Actualmente, el parámetro User ID admite el Microsoft Entra UserPrincipalName, como solo una dirección de correo electrónico.
  • topicName: parámetro 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 desea insertar en el cuadro de redacción del usuario de la aplicación actual mientras el chat está en estado borrador.

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

En el ejemplo siguiente se muestra cómo abrir un mensaje de chat a un grupo de participantes con un mensaje inicial. Puede dirigir el vínculo profundo a un chat existente o nuevo. Si ya existe un chat, se abre el vínculo profundo en ese 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 */ }

Para navegar a una conversación de chat específica en Teams, use el siguiente formato de vínculo profundo:

https://teams.microsoft.com/l/chat/<chatId>/conversations

El parámetro de consulta es chatId, que representa el identificador de chat de la conversación. El formato admitido para chatId es 19:xxx.

Ejemplo: https://teams.microsoft.com/l/chat/19:c6d70e392a384916c3262b15406d763e@thread.v2/conversations

Puede usar el siguiente formato de vínculo profundo para ir a una conversación determinada dentro del subproceso del canal:

https://teams.microsoft.com/l/message/<channelId>/<parentMessageId>?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=<parentMessageId>&teamName=<teamName>&channelName=<channelName>&createdTime=<createdTime>

Los parámetros de consulta son:

  • channelId: id. de canal de la conversación. Por ejemplo, 19:3997a8734ee5432bb9cdedb7c432ae7d@thread.tacv2.
  • tenantId: identificador de inquilino, como 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • groupId: id. de grupo del archivo. Por ejemplo, 3606f714-ec2e-41b3-9ad1-6afb331bd35d.
  • parentMessageId: id. de mensaje primario de la conversación.
  • teamName: nombre del equipo.
  • channelName: nombre del canal del equipo.

Nota:

Puede ver channelId y groupId en la dirección URL del canal.

Ejemplo: https://teams.microsoft.com/l/message/<channelId>/1648741500652?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=1648741500652&teamName=<teamName>&channelName=<channelName>&createdTime=1648741500652

Use el siguiente formato de vínculo profundo para navegar a un usuario a un mensaje en un chat personal o grupal en Teams:

https://teams.microsoft.com/l/message/{chatId}/{messageId}?tenantId=<tenantId>?context={"contextType":"chat"}

Ejemplo: https://teams.microsoft.com/l/message/19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces/1563480968434?context=%7B%22contextType%22:%22chat%22%7D

Los parámetros de consulta son:

  • chatId: identificador de chat de la conversación. El formato admitido para chatId es 19: xxx. Por ejemplo, 19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces.
    Las aplicaciones pueden leer un identificador de chat a través del contexto de la aplicación en Teams, la carga entrante al bot o a través de las API de Microsoft Graph.

    Nota:

    En el caso de los chats uno a uno con bot, la carga entrante al bot contiene el identificador de conversación en formato a:xxx.

  • messageId: identificador de mensaje único de cada mensaje en un chat. Cuando un bot publica un mensaje en el messageId chat, se devuelve . También puede obtener a través de las API de messageIdMicrosoft Graph. Por ejemplo, 1563480968434.
  • context: especifique contextType como chat.

Ejemplo: http://teams.microsoft.com/l/message/19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces/1563480968434?context=%7B%22contextType%22:%22chat%22%7D

Para navegar a un equipo determinado, use el siguiente formato de vínculo profundo:

https://teams.microsoft.com/l/team/<channelId>/conversations?groupId=<groupId>&tenantId=<tenantId>

Los parámetros de consulta son:

  • channelId: id. de canal de la conversación (dirección URL codificada). Por ejemplo, 19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2.
  • groupId: id. de grupo del archivo. Por ejemplo, 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: identificador de inquilino, como 72f988bf-86f1-41af-91ab-2d7cd011db47.

Nota:

Puede obtener channelId y groupId en la dirección URL del equipo.

Ejemplo: https://teams.microsoft.com/l/team/19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2/conversations?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47

Puede usar los siguientes formatos de vínculo profundo para navegar a canales concretos:

  • Canal estándar: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>

    Ejemplo: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47

  • Canal privado: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true

    Ejemplo: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&ngc=true

  • Canal compartido: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true&allowXTenantAccess=true

    Ejemplo: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&ngc=true&allowXTenantAccess=true

Los parámetros de consulta son:

  • channelId: id. de canal de la conversación (dirección URL codificada). Por ejemplo, 19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2.
  • channelName: nombre del canal del equipo (con codificación URL). Por ejemplo, My%20example%20channel.
  • groupId: id. de grupo del equipo. Por ejemplo, 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: identificador de inquilino, como 72f988bf-86f1-41af-91ab-2d7cd011db47.
  • ngc: indica un canal de próxima generación. Para los canales privados, debe establecerse en true.
  • allowXTenantAccess: indica un canal al que se puede acceder a través de los límites del inquilino. Para los canales compartidos, debe establecerse en true.

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

https://teams.microsoft.com/l/file/<fileId>?tenantId=<tenantId>&fileType=<fileType>&objectUrl=<objectUrl>&baseUrl=<baseUrl>&serviceName=<Name>&threadId=<threadId>&groupId=<groupId>

Los parámetros de consulta son:

  • fileId: Identificador de archivo único de Sharepoint Online, también conocido como sourcedoc. Por ejemplo, 1FA202A5-3762-4F10-B550-C04F81F6ACBD.
  • tenantId: identificador de inquilino, como 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • fileType: tipo de archivo admitido, como docx, pptx, xlsx y pdf.
  • objectUrl: dirección URL del objeto del archivo. El formato es https://{tenantName}.sharepoint.com/sites/{TeamName}/SharedDocuments/{ChannelName}/FileName.ext. Por ejemplo, https://microsoft.sharepoint.com/teams/(filepath).
  • baseUrl: dirección URL base del archivo. El formato es https://{tenantName}.sharepoint.com/sites/{TeamName}. Por ejemplo, https://microsoft.sharepoint.com/teams.
  • serviceName: nombre del servicio, id. de aplicación. Por ejemplo, teams.
  • threadId: threadID es el identificador de equipo del equipo donde se almacena el archivo. Es opcional y no se puede establecer para los archivos almacenados en la carpeta de OneDrive de un usuario. Por ejemplo, 19:<f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype>.
  • groupId: id. de grupo del archivo. Por ejemplo, ae063b79-5315-4ddb-ba70-27328ba6c31e.

Nota:

  • Puede ver threadId y groupId en la dirección URL del canal.
  • En el nuevo cliente de Teams, no se admite el formato de vínculo profundo que se usa objectURL para un archivo de un canal, que se usa objectUrl en el formato de vínculo profundo.

En el siguiente formato de ejemplo se muestra el vínculo profundo a los archivos:

https://teams.microsoft.com/l/file/5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80?tenantId=0d9b645f-597b-41f0-a2a3-ef103fbd91bb&fileType=pptx&objectUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform%2FShared%20Documents%2FFC7-%20Bot%20and%20Action%20Infra%2FKaizala%20Actions%20in%20Adaptive%20Cards%20-%20Deck.pptx&baseUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform&serviceName=teams&threadId=19:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype&groupId=ae063b79-5315-4ddb-ba70-27328ba6c31e

Serialización de este objeto

{
fileId: "5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80",
tenantId: "0d9b645f-597b-41f0-a2a3-ef103fbd91bb",
filetype: = "pptx",
objectUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform/Shared Documents/FC7- Bot and Action Infra/Kaizala Actions in Adaptive Cards - Deck.pptx",
baseUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform",
serviceName: "teams",
threadId: = "19:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype",
groupId: "ae063b79-5315-4ddb-ba70-27328ba6c31e"
}

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js
Identificador de subentidad de consumo de vínculos profundos En este ejemplo se muestra cómo usar un vínculo profundo desde un chat de bot a una pestaña que consume el identificador de subentidad. También muestra vínculos profundos para:
- Navegar a una aplicación
- Navegar a un chat
- Abrir un cuadro de diálogo de perfil
- Abrir un cuadro de diálogo de programación		 View View