Video conference extension

OverviewEndpoints

Using the video conference API, you can configure a public app to give HubSpot users the ability to add a video conference link when creating a meeting, similar to the Google Meet and Zoom integration. Using this API will involve: 

  1. Setting up your public app with video conference extension webhooks. You'll configure your app with the URIs that HubSpot will use to notify you when meetings are being created, updated, or deleted.
  2. Setting up a custom back-end to handle meeting creation and update webhooks.
  3. If needed, setting up your back-end to handle user identify verification webhooks.

All requests to the video conferencing API must be authenticated using your developer account's developer API key. You can include the key in a hapikey query parameter at the end of the request URL. You can find your developer API key in your developer account.

Prerequisites

Before getting started, ensure you've created a developer account and a public app within it.

Configure webhook URLs

So that HubSpot knows where to send notifications when meetings are created, updated, or deleted, you'll first configure the extension's webhook URLs.

To do so, make a PUT request to /crm/v3/extensions/videoconferencing/settings/{appId}?hapikey=YOUR_HUBSPOT_DEVELOPER_API_KEY.

In the request body, you'll need to include the createMeetingUrl field to set the URL that HubSpot will send meeting creation webhook payloads. You can optionally include additional webhook URLs. These values can be updated later using the same request URL.

JSON 
// Example request

{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting",
"deleteMeetingUrl": "https://example.com/delete-meeting"
}
Use this table to describe parameters / fields
FieldTypeDescription
createMeetingUrl
Required
String

The URL that HubSpot will notify when a new meeting has been created. This will include a JSON payload with the meeting details. The URL must use https protocol.

updateMeetingUrl
String

The URL that HubSpot will notify when an existing meeting has been updated. This will include a JSON payload with the updated meeting details. The URL must use https protocol.

deleteMeetingUrl
String

The URL that HubSpot will notify when an existing meeting has been deleted. This will include a conferenceId of the deleted meeting. The URL must use https protocol.

userVerifyUrl
String

The URL that HubSpot will use to verify that the user exists in the external video conferencing system. 

Example Response: 

JSON 
// Example 200 response
{
"createMeetingUrl": "https://example.com/create-meeting",
"updateMeetingUrl": "https://example.com/update-meeting",
"deleteMeetingUrl": "https://example.com/delete-meeting"
}

Retrieve webhook URLs

To retrieve webhook URLs configured for an existing app, make a GET request to /crm/v3/extensions/videoconferencing/settings/{appId}.

The response will include the currently configured webhook URLs.

JSON 
// 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 payloads

Once webhook URLs are configured, HubSpot will send payloads to those URLs when a meeting create, update, or delete event occurs.

All webhooks sent by HubSpot are HMAC signed using your app's secret. You can learn more about this in the webhooks security documentation (the rest of the page does not apply to these video conference extension webhooks).

Create meeting webhook

When a meeting is created, HubSpot will send a request to the URL specified in the createMeetingUrl field. The request payload includes information about the HubSpot account, associated HubSpot user, and meeting details.

JSON 
// Example payload
{
  "portalId": 123123,
  "userId": 123,
  "userEmail": "test.user@example.com",
  "topic": "A Test Meeting",
  "source": "MEETINGS",
  "startTime": 1534197600000,
  "endTime": 1534201200000
}
Use this table to describe parameters / fields
FieldTypeDescription
portalId
Number

The ID of the HubSpot account that the request is coming from.

userId
Number

The ID of the HubSpot user that is assigned to the meeting.

userEmail
String

The email address of the HubSpot user assigned to the meeting.

topic
String

The title of the meeting.

source
String

Indicates where the meeting was created. Can be either:

  • MEETINGS: the meeting was creating from a meeting scheduling page.
  • MANUAL: the meeting was created manually from a CRM record.
startTime
Number

The start time of the meeting in epoch milliseconds.

endTime
Number

The end time of the meeting in epoch milliseconds.

To successfully handle this webhook, you should generate a video conference for this meeting (or link it to an existing conference line), and respond with information about this conference. The fields expected in the response are:

  • conferenceId: a unique ID associated with the conference on this event.
    This ID needs to be globally unique within your system. HubSpot will return this ID
    back to you in the update webhook.
  • conferenceUrl: the URL that users can use to join the conference.
  • conferenceDetails: plain text invitation information. This should describe
    how attendees of the event can access the video conference for this
    event. Newlines will be maintained in representations of this text, but no other formatting is supported.

For example, your response might look like the following:

JSON 
//example response
{
"conferenceId": "some-unique-id",
"conferenceUrl": "https://example.com/join",
"conferenceDetails": "Click here to join: https://example.com/join"
}

Update meeting webhook

If you've specified a updateMeetingUrl , HubSpot will send this URI a request whenever a meeting's relevant details have changed. This notification is necessary if you need to maintain the most up-to date topic or times for a video conference. The request payload includes information about the HubSpot account, associated HubSpot user, and meeting details.

JSON 
//example request
{
  "conferenceId": "some-unique-id",
  "userId": 123,
  "userEmail": "test.user@example.com",
  "portalId": 123123,
  "topic": "A Test Meeting (updated)",
  "startTime": 1534197600000,
  "endTime": 1534201200000
}
Use this table to describe parameters / fields
FieldTypeDescription
conferenceId
String

The unique identifier for the conference provided by your integration in the response to the create meeting webhook.

userId
Number

The ID of the HubSpot user that is assigned to the meeting. This will always be the same user as the one in the meeting creation payload.

userEmail
String

The email address of the HubSpot user assigned to the meeting. This will always be the same user as the one in the meeting creation payload.

portalId
Number

The ID of the HubSpot account that the request is coming from.

topic
String

The title of the meeting.

startTime
Number

The start time of the meeting in epoch milliseconds.

endTime
Number

The end time of the meeting in epoch milliseconds.

No response body is required when responding to these requests. Only a 200 or 204 response code is required to let HubSpot know that this webhook was been received successfully.

Deleted meeting webhook

When a meeting is deleted in HubSpot, a request will be sent to the URL specified in the  deleteMeetingUrl field. The payload will include the conferenceId of the deleted meeting.

JSON 
// Example payload
{
"conferenceId": "some-unique-id"
}

No response body is required when responding to these requests. Only a 200 or 204 response code is required to let HubSpot know that this webhook was been received successfully.

User verification webhook

HubSpot's systems will always communicate with you about its users in terms of their HubSpot user ID and their HubSpot account email address. There is a chance that a user in HubSpot's system may exist in your system with a different email address or identifier.

Before HubSpot makes a call to your system to create, update, or delete a video conference link, it will first check the app's settings for a userVerifyUrl field. If that URL has been set, HubSpot will make a call to it to retrieve your native user identifier. It will then send that identifier as the user's email address in the subsequent call. If you do not configure this URL, HubSpot will always assume that the user's identity is verified.

This setting is optional and is up to you to determine if it's needed. If you need to maintain a user mapping within your system, you may wish to simply map the HubSpot user ID or email to your internal user ID on each call.

The payload for this webhook contains the HubSpot account ID and the user's email address.

JSON 
//example request
{
"portalId": 123123,
"userEmail": "test.user@example.com"
}

You can return a 200 response or any error code (404 would be appropriate). If you return a 200, you should return a payload containing the new ID that we should use in place of the email address:

JSON 
//example response
{
"id": "any-string-id"
}
Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.