Teams のワークフローへのディープ リンク

新しいチャットの作成、スケジュール 設定ダイアログの開き、音声ビデオ通話への移動など、Teams で特定のタスクを実行するためのディープ リンクを作成できます。

この記事では、ディープ リンクを作成する方法について説明します。

• 新しいチャットを開始するには
• 会議のスケジュール設定ダイアログを開くには
• オーディオ ビデオ通話を開始するには
• 会議でステージにコンテンツを共有するには
• 会議サイド パネルへ
• 会議に参加するには

新しいチャットを開始するためのディープ リンク

アプリケーションは、ユーザーの一覧で新しいチャットを開始し、次の形式を使用してチャット名や下書きメッセージなどの追加情報を提供できます。

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

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

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

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

ボットでこのディープ リンクを使用するには、カードのボタンの URL ターゲットとしてディープ リンクを指定するか、openUrlアクションの種類を使用してアクションをタップします。 アプリでは、Teams JavaScript クライアント ライブラリ (TeamsJS) v.2.0 以降を使用して、ディープ リンクを手動で準備することなく作成することもできます。 次の例では、TeamsJS を使用して、チャット機能がサポートされているかどうかをチェックします。

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 アプリにディープ リンクを作成して会議のスケジュール 設定ダイアログを開き、次の方法を使用して会議のタイトルや参加者などの情報を提供できます。

• 会議のスケジュール設定ダイアログを開くディープ リンクを手動で構成する
• TeamsJS ライブラリを使用してディープ リンクを構成し、会議のスケジュール ダイアログを開く

TeamsJS の型指定された API を使用することをお勧めしますが、Teams 組み込みのスケジュール ダイアログへのディープ リンクを手動で作成することもできます。

会議のスケジュール設定ダイアログを開くディープ リンクを手動で構成する

ボット、コネクタ、またはメッセージ拡張機能のカードで使用できるディープ リンクを構成する場合は、次の形式を使用します。

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

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

• attendees: 会議の出席者を表すユーザー ID のコンマ区切りリスト (省略可能)。 アクションを実行するユーザーは、会議の開催者です。 [ユーザー ID] フィールドでは、Microsoft Entra UserPrincipalName (通常はメール アドレス) のみがサポートされます。
• startTime: イベントの開始時刻の省略可能なパラメーター。 開始時刻は 長い ISO 8601 形式である必要があります(例: 2018-03-12T23:55:25+02:00)。
• endTime: イベントの終了時刻の省略可能なパラメーター 。ISO 8601 形式でもあります。
• subject: 会議の件名の省略可能なパラメーター。
• content: 会議の詳細フィールドの省略可能なパラメーター。

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

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

TeamsJS ライブラリを使用してディープ リンクを構成し、会議のスケジュール ダイアログを開く

また、Teams アプリで TeamsJS v.2.0 以降を使用して、手動でリンクを準備することなく会議のスケジュール ダイアログを開くこともできます。 Teams でスケジュール ダイアログを開くには、Teams がまだ予定表機能をサポートしていないため、元のディープ リンク URL ベースのメソッドを引き続き使用する必要があります。

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

カレンダーの操作の詳細については、API リファレンス ドキュメントのカレンダー名前空間を参照してください。

ユーザーとの音声ビデオ通話を開始するためのディープ リンク

ユーザーが 1 対 1 通話、グループ通話、またはビデオ通話を開始するためのディープ リンクを準備するように Teams アプリを構成できます。 通話の種類と参加者を指定することで、1 人のユーザーまたはユーザーのグループに対してオーディオのみの呼び出しまたはオーディオ ビデオ通話を呼び出すことができます。 Teams が通話を発信する前に、クライアントは確認を求めます。 グループ通話がある場合は、同じディープ リンク呼び出しで一連の VoIP ユーザーと PSTN ユーザーを呼び出すことができます。

ビデオ通話で、Teams クライアントは通話の発信者のビデオをオンにする前に確認を求めます。 通話の受信者は、Teams の通話通知ウィンドウを使用して、音声のみで応答するか、音声とビデオで応答するかを選択できます。

ディープ リンクは、次の 2 つの方法のいずれかで構成できます。

• ユーザーとの音声ビデオ通話を開始するようにディープ リンクを手動で構成する
• TeamsJS ライブラリを使用してディープ リンクを構成して、ユーザーとの音声ビデオ通話を開始する

ユーザーとの音声ビデオ通話を開始するようにディープ リンクを手動で構成する

TeamsJS v.2.0 以降の型指定された API を使用することをお勧めしますが、手動で構成されたディープ リンクを使用して通話を開始することもできます。 次の形式を参照してください。

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

• users: 呼び出しの参加者を表すユーザー ID のコンマ区切りのリスト。 ユーザー ID フィールドは、Microsoft Entra UserPrincipalName (通常はメール アドレス) または PSTN 通話でサポートされ、PSTN MRI 4:<phonenumber>をサポートします。
• withVideo: ビデオ通話を行うために使用できる省略可能なパラメーター。 このパラメーターを設定すると、呼び出し元のカメラのみがオンになります。 通話の受信者は、Teams 通話通知ウィンドウを通じて音声通話または音声通話とビデオ通話で応答できます。

TeamsJS ライブラリを使用してディープ リンクを構成して、ユーザーとの音声ビデオ通話を開始する

アプリケーションでは、TeamsJS v.2.0 以降を使用して、これらのディープ リンクを手動で準備することなく、呼び出しを開始することもできます。 次のコードは、TeamsJS を使用して呼び出しを開始する方法を示しています。

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

会議のステージにコンテンツを共有するためのディープ リンク

ステージでコンテンツを共有するためのディープ リンクを追加するには、アプリ コンテキストが必要です。 アプリ コンテキストを使用すると、Teams クライアントはアプリ マニフェストをフェッチし、ステージでの共有が可能な場合にチェックできます。 アプリ コンテキストの例を次に示します。

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

アプリ コンテキストのクエリ パラメーターは次のとおりです。

• appID: これは、アプリ マニフェストから取得できる ID です。
• appSharingUrl: ステージで共有する必要がある URL は、アプリ マニフェストで定義されている有効なドメインである必要があります。 URL が有効なドメインでない場合は、エラーの説明をユーザーに提供するエラー ダイアログが表示されます。
• useMeetNow: これには、true または false を指定できるブール型パラメーターが含まれます。

  • True: useMeetNow 値が true の場合、進行中の会議がない場合は、新しい会議が開始されます。 会議が進行中の場合、この値は無視されます。

  • False: useMeetNow の既定値は false です。つまり、ディープ リンクがステージに共有され、会議が進行中でなければ、予定表のポップアップが表示されます。 ただし、会議中に直接共有できます。

すべてのクエリ パラメーターが適切に URI エンコードされ、アプリ コンテキストが最終的な URL で 2 回エンコードされている必要があることを確認します。 次に例を示します。

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

ディープ リンクは、Teams Web から、または Teams デスクトップまたはモバイル クライアントから起動できます。

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

• deepLinkId: テレメトリの関連付けに使用される任意の識別子。
• fqdn: fqdn は省略可能なパラメーターで、ステージ上でアプリを共有するために会議の適切な環境に切り替えるために使用できます。 特定の環境で特定のアプリ共有が発生するシナリオをサポートします。 fqdnの既定値はエンタープライズ URL であり、使用可能な値は Teams for Life、teams.microsoft.com、またはteams.microsoft.usにTeams.live.comされます。

ディープ リンクを生成して 、アプリを共有してステージを 作成したり、会議を開始したり、会議に参加したりできます。

会議サイド パネルへのディープ リンク

会議の会議側パネルへのディープ リンクを生成できます。 会議側パネルへのディープ リンクには、次の形式を使用します。

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

例:

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

既定では、会議のサイド パネルにディープ リンクが開きます。 会議のサイド パネルではなくアプリでディープ リンクを直接開くには、ディープ リンク形式で openInMeeting=false を追加します。

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

詳細については、「 タブへのディープ リンク」を参照してください。

次のシナリオでは、会議側パネルにディープ リンクが開きません。

• アクティブな会議はありません。
• アプリマニフェストで sidePanel コンテキストが宣言されていません。
• openInMeeting はディープ リンク内の false に設定されます。
• ディープ リンクは、会議ウィンドウまたはコンポーネントの外部で選択されます。
• ディープ リンクは、別の会議で作成されたディープ リンクなど、現在の会議と一致しません。

会議に参加するためのディープ リンク

Teams アプリは、Graph API を使用して会議 URL に参加するための URL を読み取ることができます。 このディープ リンクにより、ユーザーが会議に参加するための UI が表示されます。 詳細については、「onlineMeetingを取得する」と「会議の詳細を取得する」を参照してください。

コード サンプル