Lien profond vers la conversation Teams

  • Article

Vous pouvez créer un lien profond vers une conversation Teams, par exemple pour démarrer une nouvelle conversation, accéder à une conversation de canal et accéder à un fichier au sein d’un canal.

Dans cet article, vous allez apprendre à créer :

Vous pouvez accéder à ou créer des conversations privées entre les utilisateurs avec la bibliothèque de client JavaScript Microsoft Teams (TeamsJS) en spécifiant l’ensemble des participants. Si une conversation n'existe pas avec les participants spécifiés, l'utilisateur est dirigé vers une nouvelle conversation vide.

Lorsqu’un utilisateur crée une conversation à l’aide d’un lien profond, Teams crée la nouvelle conversation dans l’état brouillon jusqu’à ce que l’utilisateur envoie le premier message. Vous pouvez également fournir le nom de la conversation si elle n’existe pas déjà, ainsi que le texte qui doit être inséré dans la zone de composition de l’utilisateur. Considérez cela comme un raccourci pour l’utilisateur effectuant l’action manuelle de naviguer vers ou de créer la conversation, puis de composer le message.

Par exemple, si vous récupérez des informations de profil utilisateur Microsoft 365 à partir de votre bot en tant que carte, ce lien profond peut permettre à l’utilisateur de l’application de discuter facilement avec cette personne.

Vous pouvez configurer des liens profonds pour démarrer une nouvelle conversation de l’une des deux manières suivantes :

Bien que l’utilisation des API typées soit recommandée, vous pouvez également utiliser le format suivant pour un lien profond créé manuellement que vous pouvez utiliser dans un bot, un connecteur ou une carte d’extension de message :

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

Pour utiliser ce lien profond avec votre bot, spécifiez le lien profond comme cible d’URL dans le bouton de votre carte ou appuyez sur action via le openUrl type d’action.

Les paramètres de requête sont les suivants :

  • users: liste d’ID utilisateur séparés par des virgules représentant les participants à la conversation. L’utilisateur qui effectue l’action est toujours inclus en tant que participant. Actuellement, le paramètre User ID prend en charge les Microsoft Entra UserPrincipalName, comme une adresse e-mail uniquement.
  • topicName: paramètre facultatif pour le nom d’affichage de la conversation si une conversation a au moins trois utilisateurs. Si ce champ n’est pas spécifié, le nom complet de la conversation est basé sur les noms des participants.
  • message: champ facultatif pour le texte du message que vous souhaitez insérer dans la zone de composition de l’utilisateur de l’application actuelle lorsque la conversation est à l’état brouillon.

Exemple : 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

L’exemple suivant montre comment ouvrir un message de conversation à un groupe de participants avec un message initial. Vous pouvez cibler le lien profond vers une conversation existante ou nouvelle. Si une conversation existe déjà, le lien profond s’ouvre dans cette conversation.

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 */ }

Pour accéder à une conversation de conversation spécifique dans Teams, utilisez le format de lien profond suivant :

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

Le paramètre de requête est chatId, qui représente l’ID de conversation de la conversation. Le format pris en charge pour chatId est 19 :xxx.

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

Vous pouvez utiliser le format de lien profond suivant pour accéder à une conversation particulière dans le thread de canal :

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

Les paramètres de requête sont les suivants :

  • channelId : ID du canal de la conversation. Par exemple : 19:3997a8734ee5432bb9cdedb7c432ae7d@thread.tacv2.
  • tenantId: ID de locataire, tel que 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • groupId : ID de groupe du fichier. Par exemple : 3606f714-ec2e-41b3-9ad1-6afb331bd35d.
  • parentMessageId: ID de message parent de la conversation.
  • teamName : nom de l’équipe.
  • channelName : nom du canal de l’équipe.

Remarque

Vous pouvez voir channelIdand groupId dans l’URL du canal.

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

Utilisez le format de lien profond suivant pour accéder à un message dans une conversation personnelle ou de groupe dans Teams :

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

Exemple : 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

Les paramètres de requête sont les suivants :

  • chatId: ID de conversation de la conversation. Le format pris en charge pour chatId est 19 : xxx. Par exemple : 19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces.
    Les applications peuvent lire un ID de conversation via le contexte de l’application dans Teams, la charge utile entrante au bot ou via les API Microsoft Graph.

    Remarque

    Pour les conversations en tête-à-tête avec bot, la charge utile entrante au bot contient l’ID de conversation au format a :xxx.

  • messageId: ID de message unique de chaque message dans une conversation. Lorsqu’un bot publie un message dans une conversation, le messageId est retourné. Vous pouvez également obtenir le messageId via les API Microsoft Graph. Par exemple : 1563480968434.
  • context: spécifiez contextType comme conversation.

Exemple : 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

Pour accéder à une équipe particulière, utilisez le format de lien profond suivant :

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

Les paramètres de requête sont les suivants :

  • channelId: ID de canal de la conversation (encodée url). Par exemple, 19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2.
  • groupId : ID de groupe du fichier. Par exemple, 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: ID de locataire, tel que 72f988bf-86f1-41af-91ab-2d7cd011db47.

Remarque

Vous pouvez obtenir et groupId dans channelId l’URL de l’équipe.

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

Vous pouvez utiliser les formats de liens profonds suivants pour accéder à des canaux particuliers :

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

    Exemple : 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 privé : https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true

    Exemple : 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 partagé : https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true&allowXTenantAccess=true

    Exemple : 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

Les paramètres de requête sont les suivants :

  • channelId: ID de canal de la conversation (encodée url). Par exemple : 19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2.
  • channelName: nom du canal de l’équipe (encodé url). Par exemple : My%20example%20channel.
  • groupId: ID de groupe de l’équipe. Par exemple : 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: ID de locataire, tel que 72f988bf-86f1-41af-91ab-2d7cd011db47.
  • ngc: indique un canal de nouvelle génération. Pour les canaux privés, vous devez définir sur true.
  • allowXTenantAccess: indique un canal accessible au-delà des limites du locataire. Pour les canaux partagés, vous devez définir sur true.

Vous pouvez utiliser le format de lien profond suivant dans un bot, un connecteur ou une extension de message carte pour configurer un lien profond afin de se connecter à un fichier dans un canal :

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

Les paramètres de requête sont les suivants :

  • fileId : ID de fichier unique de Sharepoint Online, également appelé sourcedoc. Par exemple : 1FA202A5-3762-4F10-B550-C04F81F6ACBD.
  • tenantId: ID de locataire, tel que 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • fileType : type de fichier pris en charge, tel que docx, pptx, xlsx et pdf.
  • objectUrl : URL de l’objet du fichier. Le format est https://{tenantName}.sharepoint.com/sites/{TeamName}/SharedDocuments/{ChannelName}/FileName.ext. Par exemple : https://microsoft.sharepoint.com/teams/(filepath).
  • baseUrl : URL de base du fichier. Le format est https://{tenantName}.sharepoint.com/sites/{TeamName}. Par exemple : https://microsoft.sharepoint.com/teams.
  • serviceName : nom du service, ID d’application. Par exemple : teams.
  • threadId: threadID est l’ID d’équipe de l’équipe dans laquelle le fichier est stocké. Elle est facultative et ne peut pas être définie pour les fichiers stockés dans le dossier OneDrive d’un utilisateur. Par exemple : 19:<f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype>.
  • groupId : ID de groupe du fichier. Par exemple : ae063b79-5315-4ddb-ba70-27328ba6c31e.

Remarque

  • Vous pouvez voir threadIdand groupId dans l’URL du canal.
  • Dans le nouveau client Teams, le format de lien profond utilisé objectURL pour un fichier dans un canal n’est pas pris en charge, utilisez objectUrl dans le format de lien profond.

L’exemple de format suivant illustre le lien profond vers les fichiers :

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

Sérialisation de cet objet

{
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"
}

Exemple de code

Exemple de nom Description .NET Node.js
ID de sous-entité consommatrice de lien profond Cet exemple montre comment utiliser un lien profond à partir d’une conversation de bot vers un onglet utilisant l’ID de sous-entité. Il affiche également des liens profonds pour :
- Navigation vers une application
- Navigation vers une conversation
- Ouvrir une boîte de dialogue de profil
- Ouvrir une boîte de dialogue de planification		 View View