Freigeben über

Deep-Link zum Teams-Chat

  • Artikel

Sie können einen Deep-Link zu einem Teams-Chat erstellen, z. B. um einen neuen Chat zu starten, zu einer Kanalunterhaltung zu wechseln und auf eine Datei in einem Kanal zuzugreifen.

In diesem Artikel erfahren Sie, wie Sie Folgendes erstellen:

Sie können mit der Microsoft Teams JavaScript-Clientbibliothek (TeamsJS) zu privaten Chats zwischen Benutzern navigieren oder diese erstellen, indem Sie die Gruppe der Teilnehmer angeben. Wenn kein Chat mit den angegebenen Teilnehmern vorhanden ist, wird der Benutzer zu einem leeren neuen Chat geleitet.

Wenn ein Benutzer einen neuen Chat mithilfe eines Deep-Links erstellt, erstellt Teams den neuen Chat im Entwurfszustand, bis der Benutzer die erste Nachricht sendet. Sie können auch den Namen des Chats angeben, sofern er noch nicht vorhanden ist, zusammen mit Text, der in das Verfassenfeld des Benutzers eingefügt werden soll. Betrachten Sie dies als Verknüpfung für den Benutzer, der die manuelle Aktion zum Navigieren oder Erstellen des Chats und dann das Verfassen der Nachricht durchnimmt.

Wenn Sie als Anwendungsbeispiel Microsoft 365-Benutzerprofilinformationen von Ihrem Bot als Karte abrufen, kann dieser Deep-Link es dem App-Benutzer ermöglichen, einfach mit dieser Person zu chatten.

Sie können DeepLinks konfigurieren, um einen neuen Chat auf eine der beiden folgenden Arten zu starten:

Die Verwendung der typisierten APIs wird zwar empfohlen, alternativ können Sie aber auch das folgende Format für einen manuell erstellten Deep-Link verwenden, der in einer Bot-, Connector- oder Nachrichtenerweiterungskarte verwendet werden kann:

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

Um diesen Deep-Link mit Ihrem Bot zu verwenden, geben Sie den Deep-Link als URL-Ziel in der Schaltfläche Ihres Karte an, oder tippen Sie über den Aktionstyp auf AktionopenUrl.

Die Abfrageparameter sind:

  • users: Eine durch Trennzeichen getrennte Liste von Benutzer-IDs, die die Teilnehmer des Chats darstellen. Der Benutzer, der die Aktion ausführt, ist immer als Teilnehmer enthalten. Der Parameter Benutzer-ID unterstützt die Microsoft Entra UserPrincipalName, z. B. nur eine E-Mail-Adresse.
  • topicName: Ein optionaler Parameter für den Anzeigenamen des Chats, wenn ein Chat drei oder mehr Benutzer hat. Wenn dieses Feld nicht angegeben wird, basiert der Bildschirmname des Chats auf den Namen der Teilnehmer.
  • message: Ein optionales Feld für den Nachrichtentext, den Sie in das Verfassenfeld des aktuellen App-Benutzers einfügen möchten, während sich der Chat im Entwurfszustand befindet.

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

Im folgenden Beispiel wird veranschaulicht, wie eine Chatnachricht für eine Gruppe von Teilnehmern mit einer ersten Nachricht geöffnet wird. Sie können den Deep-Link auf einen vorhandenen oder einen neuen Chat ausrichten. Wenn bereits ein Chat vorhanden ist, wird der Deep-Link in diesem Chat geöffnet.

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

Um zu einer bestimmten Chatunterhaltung in Teams zu navigieren, verwenden Sie das folgende Deep-Link-Format:

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

Der Abfrageparameter ist chatId, der die Chat-ID der Unterhaltung darstellt. Das unterstützte Format für chatId ist 19:xxx.

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

Sie können das folgende Deep Link-Format verwenden, um zu einer bestimmten Unterhaltung innerhalb des Kanalthreads zu wechseln:

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

Die Abfrageparameter sind:

  • channelId: Kanal-ID der Unterhaltung. Beispiel: 19:3997a8734ee5432bb9cdedb7c432ae7d@thread.tacv2.
  • tenantId: Mandanten-ID, z 0d9b645f-597b-41f0-a2a3-ef103fbd91bb. B. .
  • groupId: Gruppen-ID der Datei. Beispiel: 3606f714-ec2e-41b3-9ad1-6afb331bd35d.
  • parentMessageId: ID der übergeordneten Nachricht der Konversation.
  • teamName: Name des Teams.
  • channelName: Name des Kanals des Teams.

Hinweis

Sie können channelId und groupId in der URL dieses Kanals sehen.

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

Verwenden Sie das folgende Deep-Link-Format, um einen Benutzer zu einer Nachricht in einem persönlichen Oder Gruppenchat in Teams zu navigieren:

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

Die Abfrageparameter sind:

  • chatId: Chat-ID der Unterhaltung. Das unterstützte Format für chatId ist 19: xxx. Beispiel: 19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces.
    Apps können eine Chat-ID über den App-Kontext in Teams, eingehende Nutzdaten für den Bot oder über Microsoft Graph-APIs lesen.

    Hinweis

    Bei Einzelchats mit dem Bot enthält die eingehende Nutzlast für den Bot die Konversations-ID im Format a:xxx.

  • messageId: Eindeutige Nachrichten-ID jeder Nachricht in einem Chat. Wenn ein Bot eine Nachricht im Chat postet, wird zurückgegeben messageId . Sie können die messageId auch über Microsoft Graph-APIs abrufen. Beispiel: 1563480968434.
  • context: Geben Sie contextType als Chat an.

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

Sie können eine Unterhaltung mit einem Bot mithilfe einer vorab aufgefüllten Nachricht über einen Deep-Link beginnen. Verwenden Sie die Bot-ID mit 28: dem Präfix anstelle einer E-Mail-Adresse. Das Format des Deep Links lautet:

https://teams.microsoft.com/l/chat/0/0?users=28:[bot guid]&message=This%20message%20was%20triggered%20by%20a%20link!

Der Abfrageparameter ist bot guid. Dies ist das Bot-ID-Attribut im App-Manifest.

Beispiel: https://teams.microsoft.com/l/chat/0/0?users=28:47345678-2134-6534-9143-65146789012&message=This%20message%20was%20triggered%20by%20a%20link!

Der bereitgestellte Deep-Link lädt die Nachricht nur in das Chattextfeld des Bots und sendet die Nachricht nicht automatisch. Um die Nachricht zu senden, müssen Sie entweder die Schaltfläche Senden oder die EINGABETASTE drücken.

Um zu einem bestimmten Team zu navigieren, verwenden Sie das folgende Deep Link-Format:

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

Die Abfrageparameter sind:

  • channelId: Kanal-ID der Konversation (URL-codiert). Beispiel: 19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2.
  • groupId: Gruppen-ID der Datei. Beispiel: 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: Mandanten-ID, z. B. 72f988bf-86f1-41af-91ab-2d7cd011db47.

Hinweis

Sie können und groupId in der URL aus dem Team abrufenchannelId.

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

Sie können die folgenden Deep Link-Formate verwenden, um zu bestimmten Kanälen zu navigieren:

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

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

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

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

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

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

Die Abfrageparameter sind:

  • channelId: Kanal-ID der Konversation (URL-codiert). Beispiel: 19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2.
  • channelName: Name des Kanals des Teams (URL-codiert). Beispiel: My%20example%20channel.
  • groupId: Gruppen-ID des Teams. Beispiel: 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: Mandanten-ID, z 72f988bf-86f1-41af-91ab-2d7cd011db47. B. .
  • ngc: Gibt einen Kanal der nächsten Generation an. Für private Kanäle muss auf truefestgelegt werden.
  • allowXTenantAccess: Gibt einen Kanal an, auf den über Mandantengrenzen hinweg zugegriffen werden kann. Für freigegebene Kanäle muss auf truefestgelegt werden.

Das folgende Deep Link-Format kann in einem Bot, Connector oder einer Nachrichtenerweiterung Karte verwendet werden, um einen Deep Link für die Verbindung mit einer Datei in einem Kanal zu konfigurieren:

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

Die Abfrageparameter sind:

  • fileId: Eindeutige Datei-ID aus SharePoint Online, die auch als sourcedoc oder sharepointIds.listItemUniqueId in der Sharepoint Online-API-Antwort driveItem bezeichnet wird. Beispiel: 1FA202A5-3762-4F10-B550-C04F81F6ACBD.
  • tenantId: Mandanten-ID, z 0d9b645f-597b-41f0-a2a3-ef103fbd91bb. B. .
  • fileType: Unterstützter Dateityp, z. B. docx, pptx, xlsx und pdf.
  • objectUrl: Objekt-URL der Datei. Das Format ist https://{tenantName}.sharepoint.com/sites/{TeamName}/SharedDocuments/{ChannelName}/FileName.ext. Beispiel: https://microsoft.sharepoint.com/teams/(filepath).
  • baseUrl: Basis-URL der Datei. Das Format ist https://{tenantName}.sharepoint.com/sites/{TeamName}. Beispiel: https://microsoft.sharepoint.com/teams.
  • serviceName: Name des Diensts, App-ID. Beispiel: teams.
  • threadId: Die threadID ist die Team-ID des Teams, in dem die Datei gespeichert ist. Sie ist optional und kann nicht für Dateien festgelegt werden, die im OneDrive-Ordner eines Benutzers gespeichert sind. Beispiel: 19:<f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype>.
  • groupId: Gruppen-ID der Datei. Beispiel: ae063b79-5315-4ddb-ba70-27328ba6c31e.

Hinweis

  • Sie können threadId und groupId in der URL dieses Kanals sehen.
  • Im neuen Teams-Client wird das Deep Link-Format objectURL mit für eine Datei in einem Kanal nicht unterstützt. Verwenden Sie objectUrl es im Deep Link-Format.

Das folgende Beispielformat veranschaulicht den Deep-Link zu Dateien:

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

Serialisierung dieses Objekts:

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

Codebeispiel

Beispielname Beschreibung .NET Node.js
Deep Link, der die Subentity-ID verwendet In diesem Beispiel wird gezeigt, wie Sie einen Deep-Link aus einem Botchat zu einer Registerkarte verwenden, die die Subentity-ID verwendet. Außerdem werden Deep-Links für Folgendes angezeigt:
– Navigieren zu einer App
– Navigieren zu einem Chat
– Dialogfeld "Profil öffnen"
– Öffnen eines Planungsdialogfelds		 View View