最終更新日: 2025年8月22日

Run in Postman

ビデオ会議APIを使用すると、Google Meet連携やZoom連携と同じように、ユーザーがビデオ会議を作成するときにビデオ会議のリンクを追加するための公開アプリを構成できます。このAPIを使用するには、次の作業が必要です。 1.ビデオ会議拡張機能Webhookを使用した公開アプリをセットアップします。このアプリに、HubSpotがミーティングの作成、更新、削除イベントが発生した時点でユーザーに通知するために使用するURIを設定します。2.ミーティングの作成Webhookと更新Webhookを処理するカスタムのバックエンドをセットアップします。3. 必要に応じて、ユーザーID検証Webhookを処理するようにバックエンドをセットアップします。 ビデオ会議APIに送信する全てのリクエストには、開発者アカウントの開発者APIキーを使用した認証が必要になります。このキーをhapikeyクエリーパラメーターに格納して、リクエストURLの末尾に追加します。開発者アカウントで開発者APIキーを確認できます。

前提条件

手順を開始する前に、開発者アカウントを作成し、そのアカウント内で公開アプリを作成します。

Webhook URLを設定する

まず、HubSpotがミーティングの作成、更新、削除イベントが発生した時点で送信する通知の宛先を把握できるよう、Webhook URLを設定します。 それには、PUTリクエストを/crm/v3/extensions/videoconferencing/settings/{appId}?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEYに送信します。 リクエスト本文にcreateMeetingUrlフィールドを含め、このフィールドに、HubSpotがミーティング作成Webhookのペイロードの送信先とするURLを設定する必要があります。必要に応じて、他のWebhook URLも追加できます。これらの値は、同じリクエストURLを使用して後で更新できます。
// Example request

{
  "createMeetingUrl": "https://example.com/create-meeting",
  "updateMeetingUrl": "https://example.com/update-meeting",
  "deleteMeetingUrl": "https://example.com/delete-meeting"
}
フィールド説明
createMeetingUrl文字列新しいミーティングが作成されたときにHubSpotが通知するURL。このフィールドに、ミーティングの詳細を含むJSONペイロードが格納されます。URLでは、httpsプロトコルを使用する必要があります。
updateMeetingUrl文字列既存のミーティングが更新されたときにHubSpotが通知するURL。このフィールドに、更新されたミーティングの詳細を含むJSONペイロードが格納されます。URLでは、httpsプロトコルを使用する必要があります。
deleteMeetingUrl文字列既存のミーティングが削除されたときにHubSpotが通知するURL。このフィールドに、削除されたミーティングのconferenceIdが格納されます。URLでは、httpsプロトコルを使用する必要があります。
userVerifyUrl文字列HubSpotが外部ビデオ会議システム内に当該ユーザーが存在することを確認するために使用するURL。
レスポンスの例:
// Example 200 response
{
  "createMeetingUrl": "https://example.com/create-meeting",
  "updateMeetingUrl": "https://example.com/update-meeting",
  "deleteMeetingUrl": "https://example.com/delete-meeting"
}

Webhook URLを取得する

既存のアプリ用に構成されたWebhook URLを取得するには、GETリクエストを/crm/v3/extensions/videoconferencing/settings/{appId}に送信します。 返されるレスポンスに、現在構成されているWebhook URLが含まれます。
// Example 200 response
{
  "createMeetingUrl": "https://example.com/create-meeting",
  "updateMeetingUrl": "https://example.com/update- meeting",
  "deleteMeetingUrl": "https://example.com/delete-meeting",
  "userVerifyUrl": "https://example.com/user-verify"
}

Webhookペイロード

Webhook URLを設定すると、ミーティングの作成、更新、または削除イベントの発生時に、HubSpotがこれらのURLにペイロードを送信するようになります。
HubSpotから送信される全てのWebhookには、貴社のアプリシークレットを使用したHMACで署名が付けられます。詳細については、Webhookのセキュリティーに関するドキュメントをご確認ください(このページの残りの部分は、これらのビデオ会議拡張機能Webhookには当てはまりません)。

ミーティング作成Webhook

ミーティングが作成されると、HubSpotはcreateMeetingUrlフィールドで指定されたURLにリクエストを送信します。リクエストのペイロードは、HubSpotアカウントに関する情報、関連するHubSpotユーザー、ミーティングの詳細で構成されます。
// Example payload
{
  "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文字列ミーティングが作成された場所を示します。有効な値は次のとおりです。
startTime数値ミーティングの開始時刻(エポックミリ秒)。
endTime数値ミーティングの終了時刻(エポックミリ秒)。
このWebhookを正常に処理するには、開発者がこのミーティング用のビデオ会議を生成(または、既存の会議にリンク)し、その会議に関する情報をレスポンスとして返す必要があります。このレスポンス内に想定されるフィールドは次のとおりです。
  • conferenceId:このイベントで会議に関連付けられた固有のID。 このIDはシステム全体で重複しない値にする必要があります。HubSpotはこのIDを 更新Webhookで返します。
  • conferenceUrl:ユーザーが会議に参加するために使用するURL。
  • conferenceDetails:招待に関するプレーンテキストの情報。ここで、 イベントの出席者がこのビデオ会議にアクセスする方法が 説明されます。このテキスト内では改行が維持されますが、改行以外の書式はサポートされません。
例えば、次のようなレスポンスになります。
//example response
{
  "conferenceId": "some-unique-id",
  "conferenceUrl": "https://example.com/join",
  "conferenceDetails": "Click here to join: https://example.com/join"
}

ミーティング更新Webhook

updateMeetingUrlを指定した場合、HubSpotはミーティング関連の詳細が変更されるたびに、このURIにリクエストを送信します。ビデオ会議のトピックまたは開催時間を最新の状態に維持する必要がある場合は、この通知が欠かせません。リクエストのペイロードは、HubSpotアカウントに関する情報、関連するHubSpotユーザー、ミーティングの詳細で構成されます。
//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。値は常に、ミーティング作成ペイロードに含まれるユーザーの値と同じです。
userEmail文字列ミーティングに割り当てられているHubSpotユーザーのEメールアドレス。値は常に、ミーティング作成ペイロードに含まれるユーザーの値と同じです。
portalId数値リクエストの送信元HubSpotアカウントのID。
topic文字列ミーティングのタイトル。
startTime数値ミーティングの開始時刻(エポックミリ秒)。
endTime数値ミーティングの終了時刻(エポックミリ秒)。
これらのリクエストに応答する際のレスポンスに本文は必要ありません。必要なのは、このWebhookが正常に受信されたことをHubSpotに通知する200または204レスポンスコードのみです。

ミーティング削除Webhook

HubSpotでミーティングが削除されると、deleteMeetingUrlフィールドで指定されたURLにリクエストが送信されます。ペイロードには、削除されたミーティングのconferenceIdが含まれます。
// Example payload
{
  "conferenceId": "some-unique-id"
}
これらのリクエストに応答する際のレスポンスに本文は必要ありません。必要なのは、このWebhookが正常に受信されたことをHubSpotに通知する200または204レスポンスコードのみです。

ユーザー確認Webhook

HubSpotのシステムは常に貴社のシステムに対し、ユーザーのHubSpot上のユーザーIDとHubSpotアカウントのEメールアドレスを通知します。HubSpotのシステム内のユーザーが、貴社のシステム上で別のEメールアドレスまたはIDとして存在する可能性があります。 HubSpotは、ビデオ会議リンクを作成、更新、削除するために貴社のシステムを呼び出す前に、アプリの設定でuserVerifyUrlフィールドを確認します。このフィールドにURLが設定されている場合、HubSpotはネイティブユーザーIDを取得するために、そのURLを呼び出します。取得したIDは、以降のリクエストでユーザーのEメールアドレスとして送信されます。ユーザー確認用のURLが設定されていない場合、HubSpotは常に、ユーザーのIDは確認済みであると見なします。 この設定は任意であり、必要であるかどうかは自由に判断できます。システム内でユーザーマッピングを維持する必要があれば、呼び出しごとにHubSpotユーザーのIDまたはEメールアドレスを内部ユーザーIDにマッピングすることも可能です。 このWebhookのペイロードには、HubSpotアカウントIDとユーザーのEメールアドレスが含まれます。
//example request
{
  "portalId": 123123,
  "userEmail": "test.user@example.com"
}
200レスポンスまたは任意のエラーコード(404が適切です)を返すことができます。200を返す場合は、Eメールアドレスとして使用できる新しいIDを格納したペイロードを返してください。
//example response
{
  "id": "any-string-id"
}