ビデオ会議拡張機能
ビデオ会議APIを使用することにより、HubSpot内のミーティングの作成フローに接続し、ビデオ会議情報を追加できます。このAPIを使用するには、次の手順に従ってください。
- ビデオ会議拡張機能Webhookを使用してアプリをセットアップします。顧客がミーティングを作成または更新した際の通知に使用するURIを、HubSpotに提供します。
- ミーティング作成Webhookと、必要に応じてミーティング更新Webhookの処理を行います。
- 必要に応じてユーザーID検証Webhookの処理を行います。
設定API
開発者はこの設定APIを使用して、既存のアプリケーションをセットアップします。非公開アプリのアクセストークンを使用して、リクエストを認証できます。
設定オブジェクトの定義
設定オブジェクトには次のフィールドがあります。
createMeetingUri
:新しいビデオ会議のリクエストを送信する際にHubSpotが使用するURI。https
プロトコルを使用する必要があります。
updateMeetingUri
:(任意)既存のミーティングに対する更新を送信する際にHubSpotが使用するURI。このURIは通常、ユーザーがミーティングのトピックや時間を変更すると呼び出されます。httpsプロトコルを使用する必要があります。
deleteMeetingUri
:(任意)ミーティングが削除されたことを通知する際に、HubSpotが使用するURI。
userVerifyUri
:(任意)ユーザーがシステム上に存在することを確認する際に、HubSpotが使用するURI。
ビデオ会議拡張機能の設定を作成または更新する
リクエストの例:
PUT /extensions/video-conference/v1/settings?appId={your-appId}
//example request
{
"createMeetingUri": "https://example.com/create-meeting",
"updateMeetingUri": "https://example.com/update-meeting",
"deleteMeetingUri": "https://example.com/delete-meeting"
}
レスポンスの例:
// example 200 response
{
"createMeetingUri": "https://example.com/create-meeting",
"updateMeetingUri": "https://example.com/update-meeting",
"deleteMeetingUri": "https://example.com/delete-meeting"
}
レスポンスの例:
任意の値はリクエストから除外してください。空の文字列や他の値を指定すると、望ましくない動作になる可能性があります。
ビデオ会議拡張機能の設定を取得する
リクエストの例:
GET /extensions/video-conference/v1/settings?appId={your-appId}
レスポンスの例:
// example 200 response
{
"createMeetingUri": "https://example.com/create-meeting",
"updateMeetingUri": "https://example.com/update-meeting"
"deleteMeetingUri": "https://example.com/delete-meeting"
"userVerifyUri": "https://example.com/user-verify"
}
ミーティングWebhookを作成する
ミーティングが作成されると、HubSpotがcreateMeetingUri
にリクエストを送信します。
リクエストの例:
// example request
{
"portalId": 123123,
"userId": 123,
"userEmail": "test.user@example.com",
"topic": "A Test Meeting",
"source": "MEETINGS"
"startTime": 1534197600000,
"endTime": 1534201200000
}
このリクエストのフィールドを以下に示します。
portalId
:HubSpotアカウント(ポータル)のID。userId
:ミーティングを所有するHubSpotユーザーの固有ID。userEmail
:ミーティングを所有するHubSpotユーザーのEメールアドレス。topic
:ミーティングのトピック/タイトル。source
:ミーティングが作成されたHubSpotアプリ内のミーティング機能を示す、MEETINGSまたはMANUALのいずれか。
MEETINGSは、
「ミーティングリンク」機能を示します。MANUALは、
CRMのコミュニケーション機能で作成されたミーティングを示します。startTime
:ミーティングの開始時刻(エポックミリ秒)。endTime
:ミーティングの終了時刻(エポックミリ秒)。
このWebhookを正常に処理するには、開発者がこのミーティング用のビデオ会議を生成(または、既存の会議にリンク)し、その会議に関する情報をレスポンスとして返す必要があります。
レスポンスの例:
//example response
{
"conferenceId": "some-unique-id",
"conferenceUrl": "https://example.com/join",
"conferenceDetails": "Click here to join: https://example.com/join"
}
このレスポンスで想定されるフィールドを以下に示します。
conferenceId
:このイベントの会議に関連付けられた固有のID。
このIDはシステム全体で重複しない値にする必要があります。HubSpotはこのIDを
更新Webhookを通じて返します。conferenceUrl
:作成された会議に参加するためのリンク。これは
イベントの「ロケーション」フィールドに配置できます。conferenceDetails
:「招待」情報のプレーンテキスト。ここでは、
イベントの出席者に対し、このビデオ会議にアクセスする方法を
説明します。このテキスト内では改行は維持されますが、
その他の書式はサポートされません。
ミーティング更新Webhook
updateMeetingUri
を指定した場合、ミーティング関連の情報が変更されるたびに、HubSpotはこのURIにリクエストを送信します。ビデオ会議のトピックまたは開催時間を最新の状態に維持する場合には、この通知が欠かせません。
リクエストの例:
//example request
{
"conferenceId": "some-unique-id",
"userId": 123,
"userEmail": "test.user@example.com",
"portalId": 123123,
"topic": "A Test Meeting (updated)",
"startTime": 1534197600000,
"endTime": 1534201200000
}
このレスポンスで想定されるフィールドを以下に示します。
conferenceId
:ミーティング作成Webhookへのレスポンスとして、貴社の連携から提供される会議の固有ID。userId
:ミーティングを所有するHubSpotユーザーの固有ID。このIDは常に、ミーティング作成リクエストで指定されたuserIdの値と同じになります。userEmail
:ミーティングを所有するHubSpotユーザーのEメールアドレス。このEメールアドレスは常に、ミーティング作成リクエストで指定されたuserEmailの値と同じになります。topic
:ミーティングのトピック/タイトル。startTime
:ミーティングの開始時刻(エポックミリ秒)。
endTime
:ミーティングの終了時刻(エポックミリ秒)。
これらのリクエストに応答する際のレスポンスに、本文は必要ありません。必要なのは、
このWebhookが正常に受信されたかどうかを通知する200または204のレスポンスコードのみ
です。
ミーティング削除Webhook
ミーティングが削除されると、HubSpotはリクエストをdeleteMeetingUri
に送信します。
リクエストの例:
//example request
{
"conferenceId": "some-unique-id"
}
このリクエストには、削除されたミーティングのconferenceIdだけが格納されます。
これらのリクエストに応答する際のレスポンスに、本文は必要ありません。必要なのは、
このWebhookが正常に受信されたかどうかを通知する200または204のレスポンスコードのみ
です。
ユーザー確認Webhook
HubSpotのシステムは、ユーザーのHubSpot上のユーザーIDとHubSpotアカウントのEメールアドレスを、常に貴社のシステムと確認します。HubSpotのシステム内のユーザーが、貴社のシステム上で別のEメールアドレスまたはIDとして存在する可能性があります。
HubSpotはウェブ会議のリンクを作成、更新、または削除するために貴社のシステムを呼び出す前に、貴社のuserVerifyUri
が設定されているかどうかを確認します。このURIが設定されている場合はそれを呼び出して、ネイティブユーザーIDを取得します。取得したIDをユーザーのEメールアドレスとして
以降の呼び出しで送信します。
HubSpotアプリケーションでの箇所によっては、ユーザーが操作できるUIコンポーネントを表示する前に、事前検証の一環として、ユーザーが貴社のシステム上に存在することを確認するための呼び出しが行われます。ユーザー確認用のURIが設定されていない場合、HubSpotは常に、ユーザーのIDを確認済みと見なします。
この機能への対応は任意です。システム内でユーザーマッピングを維持する必要があれば、呼び出しごとにHubSpotユーザーのIDまたはEメールアドレスを内部ユーザーIDにマッピングすることも可能です。
このリクエストの例を次に示します。
//example request
{
"portalId": 123123,
"userEmail": "test.user@example.com"
}
200でも、エラーコード(404が適切です)でも返してかまいません。200を返す場合は、「Eメールアドレス」として使用できる新しいIDを格納したペイロードを返してください。
//example response
{
"id": "any-string-id"
}
Webhook署名
HubSpotから送信される全てのWebhookには、貴社のアプリケーションの「アプリシークレット」を使用したHMACの署名が付けられます。このページの「セキュリティー」セクションをご参照ください(概要ページのその他の部分は、ビデオ会議拡張機能Webhookには適用されません)。
貴重なご意見をありがとうございました。