会議アプリ API リファレンス

会議の拡張性では、会議のエクスペリエンスを向上させるための API が提供されます。 掲載されている API のヘルプを使用すると、次のことを実行できます。

  • 会議のライフサイクル内でアプリをビルドしたり、既存のアプリを統合したりする。
  • API を使用して、アプリに会議を認識させる。
  • 会議のエクスペリエンスを向上させるために必要な API を選択する。

注意

会議のサイド パネルで SSO を動作させるには、Teams JavaScript SDK (バージョン: 1.10 以降) を使用します。

次の表に、Microsoft Teams クライアント (MSTC) および Microsoft Bot Framework (MSBF) SDK で使用可能な API の一覧を示します。

メソッド 説明 ソース
ユーザー コンテキストを取得する コンテキスト情報を取得して、関連するコンテンツを [Teams] タブに表示します。 MSTC SDK
参加者を取得する 会議 ID と参加者 ID によって参加者情報を取得します。 MSBF SDK
会議中の通知を送信する ユーザー ボット チャット用の既存の会話通知 API を使用して会議のシグナルを提供し、会議中の通知を示すユーザー アクションを通知できます。 MSBF SDK
会議の詳細を取得する 会議の静的メタデータを取得します。 MSBF SDK
リアルタイム キャプションを送信する 進行中の会議にリアルタイム キャプションを送信します。 MSTC SDK
アプリ コンテンツをステージに共有する 会議でアプリのサイド パネルからアプリの特定の部分を会議ステージに対して共有します。 MSTC SDK
アプリ コンテンツ ステージの共有状態を取得する 会議ステージでアプリの共有状態に関する情報を取得します。 MSTC SDK
アプリ コンテンツ ステージの共有機能を取得する 共有のためのアプリの機能を会議ステージに取得します。 MSTC SDK
リアルタイムの Teams 会議イベントを取得する 実際の開始時刻や終了時刻など、リアルタイムの会議イベントを取得します。 MSBF SDK

ユーザー コンテキストを取得する API

タブ コンテンツのコンテキスト情報を識別して取得するには、Teams タブのコンテキストを取得する方法に関するページを参照してください。meetingId は、会議コンテキストで実行されているタブによって使用され、応答ペイロードに追加されます。

参加者を取得する API

GetParticipant API には、認証トークンを生成するために、ボットの登録と ID が必要です。 詳細については、ボットの登録と ID に関するページを参照してください。

注意

  • 会議の開催者はいつでもロールを変更できるため、参加者のロールをキャッシュしないでください。
  • 現在、GetParticipant API は、参加者が 350 人未満の配布リストまたは名簿でのみサポートされています。

クエリ パラメーター

ヒント

参加者 ID とテナント ID は、タブの SSO 認証から取得します。

Meeting API には、URL パラメーターとして meetingIdparticipantIdtenantId が必要です。 これらのパラメーターは、Teams クライアント SDK とボット アクティビティの一部として使用できます。

次の表に、クエリ パラメーターを示します。

必須 説明
meetingId String はい 会議識別子は、Bot Invoke および Teams クライアント SDK を通して入手できます。
participantId String はい 参加者 ID はユーザー ID です。 タブ SSO、Bot Invoke、および Teams クライアント SDK で入手できます。 タブ SSO から参加者 ID を取得することをお勧めします。
tenantId String はい テナント ユーザーにはテナント ID が必要です。 タブ SSO、Bot Invoke、および Teams クライアント SDK で入手できます。 タブ SSO からテナント ID を取得することをお勧めします。

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  TeamsMeetingParticipant participant = await TeamsInfo.GetMeetingParticipantAsync(turnContext, "yourMeetingId", "yourParticipantId", "yourParticipantTenantId").ConfigureAwait(false);
  TeamsChannelAccount member = participant.User;
  MeetingParticipantInfo meetingInfo = participant.Meeting;
  ConversationAccount conversation = participant.Conversation;

  await turnContext.SendActivityAsync(MessageFactory.Text($"The participant role is: {meetingInfo.Role}"), cancellationToken);
}

応答コード

次の表に、応答コードを示します。

応答コード 説明
403 参加者情報の取得がアプリと共有されていません。 アプリが会議にインストールされていない場合は、エラー応答 403 がトリガーされます。 ライブ サイト移行中にテナント管理者がアプリを無効化またはブロックすると、エラー応答 403 がトリガーされます。
200 参加者の情報が正常に取得されました。
401 アプリは無効なトークンで応答しました。
404 会議の有効期限が切れているか、参加者が利用できません。

会議中の通知を送信する

会議のすべてのユーザーは、会議中の通知のペイロードを通して送信された通知を受け取ります。 会議中の通知のペイロードは、会議中の通知をトリガーし、ユーザー ボット チャット用の既存の会話通知 API を使用して配信される会議シグナルを提供することができます。 ユーザーの操作に基づいて、会議中の通知を送信できます。 ペイロードは Bot Service を通して入手できます。

注意

  • 会議中の通知が呼び出されると、コンテンツはチャット メッセージとして提示されます。
  • 現在、対象を指定した通知の送信と、Web アプリのサポートはサポートされていません。
  • ユーザーが Web ビューでアクションを実行した後に自動的に閉じるには、submitTask() 関数を呼び出す必要があります。 これは、アプリの申請の要件です。 詳細については、Teams SDK のタスク モジュールをご覧ください。
  • アプリで匿名ユーザーをサポートする場合は、最初の呼び出し要求ペイロードが、from.aadObjectId 要求メタデータではなく、from オブジェクトの from.id 要求メタデータに依存している必要があります。 from.id はユーザー ID であり、from.aadObjectId はユーザーの Microsoft Azure Active Directory (Azure AD) ID です。 詳細については、「タブでタスク モジュールを使用する」と「タスク モジュールの作成と送信」をご覧ください。

クエリ パラメーター

次の表に、クエリ パラメーターを示します。

必須 説明
conversationId String はい 会話識別子は Bot Invoke の一部として入手できます。

Bot ID はマニフェスト内で宣言され、ボットは結果オブジェクトを受け取ります。

注意

  • 要求されたペイロードの例では、externalResourceUrlcompletionBotId パラメーターは省略可能です。
  • externalResourceUrl の幅と高さのパラメーターは、ピクセル単位にする必要があります。 詳細については、デザイン ガイドラインのページをご覧ください。
  • URL は、会議中の通知に <iframe> として読み込まれるページです。 ドメインは、アプリのマニフェストでアプリの validDomains 配列に含まれている必要があります。
Activity activity = MessageFactory.Text("This is a meeting signal test");
activity.TeamsNotifyUser(true, "https://teams.microsoft.com/l/bubble/APP_ID?url=<url>&height=<height>&width=<width>&title=<title>&completionBotId=BOT_APP_ID");
await turnContext.SendActivityAsync(activity).ConfigureAwait(false);

応答コード

次の表に、応答コードを示します。

応答コード 説明
201 シグナルを含むアクティビティが正常に送信されました。
401 アプリは無効なトークンで応答しました。
403 アプリがシグナルを送信できません。 403 応答コードは、ライブ サイト移行中にテナント管理者がアプリを無効にしてブロックするなど、さまざまな理由で発生する可能性があります。 この場合、ペイロードには詳細なエラー メッセージが含まれています。
404 会議チャットが存在しません。

会議の詳細を取得する API

会議の詳細 API を使用すると、アプリで会議の静的メタデータを取得できます。 このメタデータは、動的には変更されないデータ ポイントを提供します。 この API は、Bot Service を通して利用できます。 現在、プライベートのスケジュールされた会議と定期的な会議、チャネルのスケジュールされた会議と定期的な会議の両方で、それぞれ異なる RSC アクセス許可を使用した API がサポートされています。

Meeting Details API には、ボットの登録とボット ID が必要です。 Bot SDK で TurnContext を取得する必要があります。 会議の詳細 API を使用するには、プライベート会議やチャネル会議など、会議の範囲に基づいて異なる RSC アクセス許可を取得する必要があります。

前提条件

会議の詳細 API を使用するには、プライベート会議やチャネル会議など、会議の範囲に基づいて異なる RSC アクセス許可を取得する必要があります。


アプリ マニフェスト バージョン 1.12 の場合

次の例では、プライベート会議についてアプリ マニフェストの webApplicationInfo および authorization プロパティを構成します。

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
        ]
    }
}

次の例では、チャネル会議についてアプリ マニフェストの webApplicationInfo および authorization プロパティを構成します。

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]
    }
}


アプリ マニフェスト バージョン 1.11 以前の場合

次の例では、プライベート会議についてアプリ マニフェストの webApplicationInfo プロパティを構成します。

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat"
    ]
}

次の例では、チャネル会議についてアプリ マニフェストの webApplicationInfo プロパティを構成します。

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "ChannelMeeting.ReadBasic.Group"
    ]
}

注意

ボットは、RSC アクセス許可のマニフェストに ChannelMeeting.ReadBasic.Group を追加することで、すべてのチャネルで作成されたすべての会議から会議の開始イベントまたは終了イベントを自動的に受信できます。

クエリ パラメーター

次の表に、クエリ パラメーターを示します。

必須 説明
meetingId String はい 会議識別子は、Bot Invoke および Teams クライアント SDK を通して入手できます。

MeetingInfo result = await TeamsInfo.GetMeetingInfoAsync(turnContext);
await turnContext.SendActivityAsync(JsonConvert.SerializeObject(result));

リアルタイム キャプション API を送信する

リアルタイム キャプション送信 API は、Microsoft Teams コミュニケーション アクセス リアルタイム翻訳 (CART) キャプションと、手入力されたクローズド キャプション用の POST エンドポイントを公開します。 このエンドポイントに送信されたテキスト コンテンツは、エンド ユーザーがキャプションを有効にした場合、Microsoft Teams 会議でエンド ユーザーに表示されます。

CART URL

POST エンドポイントの CART URL は、Microsoft Teams 会議の [会議オプション] ページから取得できます。 詳細については、「Microsoft Teams 会議での CART キャプション」をご覧ください。 CART キャプションを使用するために CART URL を変更する必要はありません。

クエリ パラメーター

CART URL には、次のクエリ パラメーターが含まれています。

必須 説明
meetingId String はい 会議識別子は、Bot Invoke および Teams クライアント SDK を通して入手できます。
例: meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d
token String はい 認可トークン。
例: token=04751eac

https://api.captions.office.microsoft.com/cartcaption?meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d&token=gjs44ra

メソッド

Resource メソッド 説明
/cartcaption POST 開始された会議のキャプションを処理します

注意

すべての要求のコンテンツ タイプが UTF-8 エンコードのプレーンテキストであることを確認してください。 要求の本文には、キャプションのみが含まれます。

POST /cartcaption?meetingid=04751eac-30e6-47d9-9c3f-0b4ebe8e30d9&token=04751eac&lang=en-us HTTP/1.1
Host: api.captions.office.microsoft.com
Content-Type: text/plain
Content-Length: 22
Hello I’m Cortana, welcome to my meeting. 

注意

POST 要求ごとに、キャプションの新しい行が生成されます。エンド ユーザーがコンテンツを読む十分な時間を確保するために、各 POST 要求本文を 80 から 120 文字に制限します。

エラー コード

次の表に、エラー コードを示します。

エラー コード 説明
400 要求が正しくありません。 応答本文に、詳細な情報があります。 たとえば、必要なパラメーターの一部が提示されていません。
401 承認されていません。不適切な/期限切れのトークンです。このエラーが発生した場合は、Teams で新しい CART URL を生成してください。
404 会議が見つからないか、開始されていません。 このエラーが発生した場合は、会議を開始してキャプションの開始を選択したことを確認してください。 会議でキャプションを有効にした後、会議へのキャプションの POST を開始できます。
500 内部サーバー エラーです。詳細については、「サポートにお問い合わせいただくかフィードバックをお寄せください」を参照してください。

アプリ コンテンツをステージに共有する API

shareAppContentToStage API を使用すると、アプリの特定の部分を会議ステージに対して共有できます。 この API は、Teams クライアント SDK を通して使用できます。

前提条件

  • shareAppContentToStage API を使用するには、RSC アクセス許可を取得する必要があります。 アプリ マニフェストで、authorization プロパティと、resourceSpecific フィールドの name および type を構成します。 次に例を示します。

    "authorization": {
        "permissions": { 
        "resourceSpecific": [
        { 
        "name": "MeetingStage.Write.Chat",
        "type": "Delegated"
        }
        ]
    }
    }
    
  • appContentUrl は、manifest.json 内の validDomains 配列で許可されている必要があります。それ以外の場合、API は 501 を返します。

クエリ パラメーター

次の表に、クエリ パラメーターを示します。

必須 説明
callback String はい コールバックには、エラーと結果という 2 つのパラメーターが含まれています。 エラー には、エラーの種類 SdkError が含まれるか、共有が成功した場合は null が含まれます。 結果 には、共有が成功した場合は true の値が含まれ、共有が失敗した場合は null が含まれます。
appContentURL String はい ステージ上で共有される URL。

const appContentUrl = "https://www.bing.com/";

microsoftTeams.meeting.shareAppContentToStage((err, result) => {
    if (result) {
        // handle success
    }
    if (err) {
        // handle error
    }
}, appContentUrl);

応答コード

次の表に、応答コードを示します。

応答コード 説明
500 内部エラー。
501 API は、現在のコンテキストではサポートされていません。
1000 アプリには、ステージに対する共有を許可する適切なアクセス許可がありません。

アプリ コンテンツ ステージの共有状態を取得する API

getAppContentStageSharingState API を使用すると、会議ステージでのアプリの共有に関する情報を取得できます。

クエリ パラメーター

次の表に、クエリ パラメーターを示します。

必須 説明
callback String はい コールバックには、エラーと結果という 2 つのパラメーターが含まれています。 エラー には、エラーの場合はエラーの種類 SdkError が含まれ、共有が成功した場合は null が含まれます。 結果 には、取得に成功したことを示す AppContentStageSharingState オブジェクトが含まれるか、取得に失敗したことを示す null が含まれます。

microsoftTeams.meeting.getAppContentStageSharingState((err, result) => {
    if (result.isAppSharing) {
        // Indicates app has permission to share contents to meeting stage.
    }
});

getAppContentStageSharingState API の JSON 応答本文は次のとおりです。

{
   "isAppSharing":true
} 

応答コード

次の表に、応答コードを示します。

応答コード 説明
500 内部エラー。
501 API は、現在のコンテキストではサポートされていません。
1000 アプリには、ステージに対する共有を許可する適切なアクセス許可がありません。

アプリ コンテンツ ステージの共有機能を取得する API

getAppContentStageSharingCapabilities API を使用すると、会議ステージに対して共有するためのアプリの機能を取得できます。

クエリ パラメーター

次の表に、クエリ パラメーターを示します。

必須 説明
callback String はい コールバックには、エラーと結果という 2 つのパラメーターが含まれています。 エラー には、エラーの種類 SdkError が含まれるか、共有が成功した場合は null が含まれます。 結果には、取得に成功したことを示す AppContentStageSharingState オブジェクトが含まれるか、取得に失敗したことを示す null が含まれます。

microsoftTeams.meeting.getAppContentStageSharingCapabilities((err, result) => {
    if (result.doesAppHaveSharePermission) {
        // Indicates app has permission to share contents to meeting stage.
    }
});

getAppContentStageSharingCapabilities API の JSON 応答本文は次のとおりです。

{
   "doesAppHaveSharePermission":true
} 

応答コード

次の表に、応答コードを示します。

応答コード 説明
500 内部エラー。
1000 アプリには、ステージに対する共有を許可するアクセス許可がありません。

リアルタイムの Teams 会議イベントを取得する API

ユーザーはリアルタイムの会議イベントを受信できます。 アプリが会議に関連付けられるとすぐに、実際の会議の開始時刻と終了時刻がボットと共有されます。 会議の実際の開始時刻と終了時刻は、スケジュールされた開始時刻と終了時刻とは異なります。 会議の詳細 API は、スケジュールされた開始時刻と終了時刻を提供します。 イベントは、実際の開始時刻と終了時刻を提供します。

Bot SDK を通して使用できる TurnContext オブジェクトに精通している必要があります。 TurnContext 内の Activity オブジェクトには、実際の開始時刻と終了時刻が入ったペイロードが含まれています。 リアルタイム会議イベントには、Teams プラットフォームからの登録されたボット ID が必要です。 ボットは、マニフェストに ChannelMeeting.ReadBasic.Group を追加することで、会議の開始イベントまたは終了イベントを自動的に受信できます。

前提条件

アプリ マニフェストには、会議の開始イベントと終了イベントを受信するための webApplicationInfo プロパティが必要です。 マニフェストを構成するには、次の例を使用します。


アプリ マニフェスト バージョン 1.12 の場合
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    },
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
        ]    
    }
}


アプリ マニフェスト バージョン 1.11 以前の場合
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat"
    ]
}

MeetingStartEndEventvalue を取得する例

ボットは OnEventActivityAsync ハンドラーを通してイベントを受け取ります。 JSON ペイロードを逆シリアル化するために、会議のメタデータを取得するモデル オブジェクトが導入されます。 会議のメタデータは、イベント ペイロード内の value プロパティにあります。 MeetingStartEndEventvalue モデル オブジェクトが作成され、そのメンバー変数はイベント ペイロード内の value プロパティの下のキーに対応します。

注意

  • 会議 ID は turnContext.ChannelData から取得します。
  • 会話 ID は会議 ID として使用しないでください。
  • 会議イベント ペイロード turncontext.activity.value からの会議 ID は使用しないでください。

次のコードは、会議の開始および終了イベントから、会議のメタデータである MeetingTypeTitleIdJoinUrlStartTimeEndTime をキャプチャする方法を示しています。

会議の開始イベント

protected override async Task OnTeamsMeetingStartAsync(MeetingStartEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

会議の終了イベント

protected override async Task OnTeamsMeetingEndAsync(MeetingEndEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

会議の開始イベントのペイロードの例

次のコードは、会議の開始イベントのペイロードの例を示しています。

{ 
    "name": "application/vnd.microsoft.meetingStart", 
    "type": "event", 
    "timestamp": "2021-04-29T16:10:41.1252256Z", 
    "id": "123", 
    "channelId": "msteams", 
    "serviceUrl": "https://microsoft.com", 
    "from": { 
        "id": "userID", 
        "aadObjectId": "aadOnjectId" 
    }, 
    "conversation": { 
        "isGroup": true, 
        "tenantId": "tenantId", 
        "id": "thread id" 
    }, 
    "recipient": { 
        "id": "user Id", 
        "name": "user name" 
    }, 
    "entities": [ 
        { 
            "locale": "en-US", 
            "country": "US", 
            "type": "clientInfo" 
        } 
    ], 
    "channelData": { 
        "tenant": { 
            "id": "channel id" 
        }, 
        "source": null, 
        "meeting": { 
            "id": "meeting id" 
        } 
    }, 
    "value": { 
        "MeetingType": "Scheduled", 
        "Title": "Meeting Start/End Event", 
        "Id": "meeting id", 
        "JoinUrl": "url" 
        "StartTime": "2021-04-29T16:17:17.4388966Z" 
    }, 
    "locale": "en-US" 
}

会議の終了イベントのペイロードの例

次のコードは、会議の終了イベントのペイロードの例を示しています。

{ 
    "name": "application/vnd.microsoft.meetingEnd", 
    "type": "event", 
    "timestamp": "2021-04-29T16:17:17.4388966Z", 
    "id": "123", 
    "channelId": "msteams", 
    "serviceUrl": "https://microsoft.com", 
    "from": { 
        "id": "user id", 
        "aadObjectId": "aadObjectId" 
    }, 
    "conversation": { 
        "isGroup": true, 
        "tenantId": "tenantId", 
        "id": "thread id" 
    }, 
    "recipient": { 
        "id": "user id", 
        "name": "user name" 
    }, 
    "entities": [ 
        { 
            "locale": "en-US", 
            "country": "US", 
            "type": "clientInfo" 
        } 
    ], 
    "channelData": { 
        "tenant": { 
            "id": "channel id" 
        }, 
        "source": null, 
        "meeting": { 
            "id": "meeting Id" 
        } 
    }, 
    "value": { 
        "MeetingType": "Scheduled", 
        "Title": "Meeting Start/End Event in Canary", 
        "Id": "19:meeting_NTM3ZDJjOTUtZGRhOS00MzYxLTk5NDAtMzY4M2IzZWFjZGE1@thread.v2", 
        "JoinUrl": "url", 
        "EndTime": "2021-04-29T16:17:17.4388966Z" 
    }, 
    "locale": "en-US" 
}

コード サンプル

サンプルの名前 説明 C# Node.js
会議の拡張性 トークンを渡すための Microsoft Teams 会議拡張性サンプル。 表示 表示
会議コンテンツ バブル ボット 会議でコンテンツ バブル ボットと対話するための Microsoft Teams 会議拡張性サンプル。 表示 表示
会議 meetingSidePanel 会議中のサイド パネルと対話するための Microsoft Teams 会議拡張性サンプル。 表示 表示
会議の [詳細] タブ 会議中の [詳細] タブと対話するための Microsoft Teams 会議拡張性サンプル。 表示 表示
会議イベントのサンプル リアルタイムの Teams 会議イベントを示すサンプル アプリ 表示 表示
採用会議のサンプル 採用シナリオの会議エクスペリエンスを示すサンプル アプリ。 表示 表示
QR コードを使用したアプリのインストール QR コードを生成し、QR コードを使用してアプリをインストールするサンプル アプリ 表示 表示

関連項目

次の手順