Teams チャットへのディープ リンク

  • [アーティクル]

新しいチャットを開始したり、チャネルの会話に移動したり、チャネル内のファイルにアクセスしたりするなど、Teams チャットへのディープ リンクを作成できます。

この記事では、次を作成する方法について説明します。

参加者のセットを指定することで、Microsoft Teams JavaScript クライアント ライブラリ (TeamsJS) を使用して、ユーザー間でプライベート チャットに移動したり、作成したりできます。 指定された参加者とチャットが存在しない場合、ユーザーは空白の新しいチャットに案内されます。

ユーザーがディープ リンクを使用して新しいチャットを作成すると、ユーザーが最初のメッセージを送信するまで、Teams は下書き状態で新しいチャットを作成します。 チャットがまだ存在しない場合は、チャットの名前と、ユーザーの新規作成ボックスに挿入するテキストを指定することもできます。 これは、ユーザーがチャットに移動または作成する手動操作を実行し、メッセージを作成するためのショートカットと考えてください。

ユース ケースの例として、ボットから Microsoft 365 ユーザー プロファイル情報をカードとして取得する場合、このディープ リンクを使用すると、アプリ ユーザーはそのユーザーと簡単にチャットできます。

ディープ リンクを構成して、次の 2 つの方法のいずれかで新しいチャットを開始できます。

型指定された API の使用をお勧めしますが、ボット、コネクタ、またはメッセージ拡張カードで使用できる手動で作成されたディープ リンクには、次の形式を使用することもできます。

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

ボットでこのディープ リンクを使用するには、カードのボタンの URL ターゲットとしてディープ リンクを指定するか、 openUrl アクションの種類でアクションをタップします。

クエリ パラメーターは次のとおりです。

  • users: チャットの参加者を表すユーザー ID のコンマ区切りのリスト。 アクションを実行するユーザーは、常に参加者として含まれます。 User ID パラメーターは、電子メール アドレスのみなど、Microsoft Entra UserPrincipalNameをサポートします。
  • topicName: チャットに 3 人以上のユーザーがある場合の、チャットの表示名の省略可能なパラメーター。 このフィールドが指定されていない場合、チャットの表示名は参加者の名前に基づいています。
  • message: チャットが下書き状態にあるときに、現在のアプリ ユーザーの作成ボックスに挿入するメッセージ テキストの省略可能なフィールド。

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

次の例では、初回のメッセージとともに参加者グループにチャット メッセージを開示する方法を示します。 既存のチャットまたは新しいチャットへのディープ リンクをターゲットにすることができます。 チャットが既に存在する場合は、そのチャットでディープ リンクが開きます。

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

Teams で特定のチャット会話に移動するには、次のディープ リンク形式を使用します。

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

クエリ パラメーターは、会話のチャット ID を表す chatId。 chatIdでサポートされている形式は 19:xxx です。

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

次のディープ リンク形式を使用して、チャネル スレッド内の特定の会話に移動できます。

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

クエリ パラメーターは次のとおりです。

  • channelId: 会話のチャネル ID。 たとえば、「 19:3997a8734ee5432bb9cdedb7c432ae7d@thread.tacv2 」のように入力します。
  • tenantId: テナント ID ( 0d9b645f-597b-41f0-a2a3-ef103fbd91bbなど)。
  • groupId: ファイルのグループ ID。 たとえば、「 3606f714-ec2e-41b3-9ad1-6afb331bd35d 」のように入力します。
  • parentMessageId: 会話の親メッセージ ID。
  • teamName: チームの名前。
  • channelName: チームのチャネルの名前。

注:

チャネルからの URL に channelId と groupId が表示されます。

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

次のディープ リンク形式を使用して、Teams の個人用チャットまたはグループ チャット内のメッセージにユーザーを移動します。

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

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

クエリ パラメーターは次のとおりです。

  • chatId: 会話のチャット ID。 chatIdでサポートされている形式は 19: xxx です。 たとえば、「 19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces 」のように入力します。
    アプリは、Teams のアプリ コンテキスト、ボットへの受信ペイロード、または Microsoft Graph API を介してチャット ID を読み取ることができます。

    注:

    ボットとの 1 対 1 のチャットの場合、ボットへの受信ペイロードには、メッセージ交換 ID が xxx 形式で含まれます。

  • messageId: チャット内の各メッセージの一意のメッセージ ID。 ボットがチャットでメッセージを投稿すると、 messageId が返されます。 Microsoft Graph API を使用してmessageIdを取得することもできます。 たとえば、「 1563480968434 」のように入力します。
  • context: contextType をチャットとして指定します。

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

特定のチームに移動するには、次のディープ リンク形式を使用します。

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

クエリ パラメーターは次のとおりです。

  • channelId: 会話のチャネル ID (URL エンコード)。 たとえば、19%3ATWLPKo8lD4v8zDxyw4FnDY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2 です。
  • groupId: ファイルのグループ ID。 たとえば、72602e12-78ac-474c-99d6-f619710353a9 です。
  • tenantId: テナント ID (72f988bf-86f1-41af-91ab-2d7cd011db47 など)。

注:

channelIdとgroupIdは、チームから URL で取得できます。

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

次のディープ リンク形式を使用して、特定のチャネルに移動できます。

  • 標準チャネル: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>

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

  • プライベート チャネル: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true

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

  • 共有チャネル: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true&allowXTenantAccess=true

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

クエリ パラメーターは次のとおりです。

  • channelId: 会話のチャネル ID (URL エンコード)。 たとえば、「 19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2 」のように入力します。
  • channelName: チームのチャネルの名前 (URL エンコード)。 たとえば、「 My%20example%20channel 」のように入力します。
  • groupId: チームのグループ ID。 たとえば、「 72602e12-78ac-474c-99d6-f619710353a9 」のように入力します。
  • tenantId: テナント ID ( 72f988bf-86f1-41af-91ab-2d7cd011db47など)。
  • ngc: 次世代チャネルを示します。 プライベート チャネルの場合は、 trueに設定する必要があります。
  • allowXTenantAccess: テナントの境界を越えてアクセスできるチャネルを示します。 共有チャネルの場合は、 trueに設定する必要があります。

チャネル内のファイルに接続するディープ リンクを構成するには、ボット、コネクタ、またはメッセージ拡張カードで次のディープ リンク形式を使用できます。

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

クエリ パラメーターは次のとおりです。

  • fileId: Sharepoint Online の一意のファイル ID (sourcedoc とも呼ばれます)。 たとえば、「 1FA202A5-3762-4F10-B550-C04F81F6ACBD 」のように入力します。
  • tenantId: テナント ID ( 0d9b645f-597b-41f0-a2a3-ef103fbd91bbなど)。
  • fileType: .docx、.pptx、.xlsx、.pdf などのサポートされているファイルの種類
  • objectUrl: ファイルのオブジェクト URL。 形式は https://{tenantName}.sharepoint.com/sites/{TeamName}/SharedDocuments/{ChannelName}/FileName.ext です。 たとえば、「 https://microsoft.sharepoint.com/teams/(filepath) 」のように入力します。
  • baseUrl: ファイルのベース URL。 形式は https://{tenantName}.sharepoint.com/sites/{TeamName} です。 たとえば、「 https://microsoft.sharepoint.com/teams 」のように入力します。
  • serviceName: サービスの名前、アプリ ID。 たとえば、「 teams 」のように入力します。
  • threadId: threadID は、ファイルが格納されているチームのチーム ID です。 これはオプションであり、ユーザーの OneDrive フォルダーに保存されているファイルには設定できません。 たとえば、「 19:<f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype> 」のように入力します。
  • groupId: ファイルのグループ ID。 たとえば、「 ae063b79-5315-4ddb-ba70-27328ba6c31e 」のように入力します。

注:

  • チャネルからの URL に threadId と groupId が表示されます。
  • 新しい Teams クライアントでは、チャネル内のファイルに objectURL を使用するディープ リンク形式はサポートされていません。ディープ リンク形式で objectUrl を使用します。

次のフォーマット例は、ファイルへのディープ リンクを示しています。

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

このオブジェクトのシリアル化

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

コード サンプル

サンプルの名前 説明 .NET Node.js
ディープ リンクを使用するサブエンティティ ID このサンプルでは、ボット チャットからサブエンティティ ID を使用するタブへのディープ リンクを使用する方法を示します。 また、次のディープ リンクも表示されます。
- アプリへの移動
- チャットへの移動
- プロファイル ダイアログを開く
- スケジュール 設定ダイアログを開く		 表示 表示