Calling extensions SDK

This feature allows apps to provide a custom calling service to HubSpot users directly within CRM records.

A calling extension consists of three main components:

  1. The calling Extensions SDK, a JavaScript SDK that enables communication between your app and HubSpot.
  2. The calling settings endpoints, which are used to set the calling settings for your app. Each HubSpot account that connects your app will use these settings.
  3. The calling iframe, which displays your app to HubSpot users and is configured using the Calling Settings endpoints.

See this knowledge base article for more details on the in-app calling experience. Once your calling extension-enabled app is connected to HubSpot, it will appear as an option in the call switcher whenever a user makes a call from HubSpot.

Note: Only outgoing calls are currently supported.

The calling extensions SDK

The calling extensions SDK is a JavaScript library that's used to communicate between HubSpot and your calling app, which will be displayed inside an iframe. This communication includes:

  • HubSpot telling your app which number to call
  • Your app telling HubSpot when the call has connected and when it's been completed.
  • HubSpot telling your app the ID of the placeholder engagement that needs to be updated with the call details.

You can find the SDK in this GitHub repository, along with the technical requirements and usage details for the SDK within your web app.

Setup

Calling extensions are configured as part of a HubSpot app. If you don't have an app, you can create one from your HubSpot developer account. (Don't have a developer account? Sign up for one here.)

Once you've configured the calling settings for your app (a one-time task), they'll apply for all users connecting it to their HubSpot account. See the Endpoints tab for reference on how to create those settings.

After your call settings are ready, users will need to go through the app connection process to make your calling service available on their HubSpot account. 

The calling process

Calls made using calling extensions go through the following steps:

  1. The user clicks the call button on a CRM record.
  2. The user selects your app as the call provider and clicks the "Call from browser" button.
  3. An iframe opens to the URL specified in the calling settings in your app.
  4. The call is completed through your app (displayed in the iframe).
  5. HubSpot creates a placeholder engagement, and sends the ID of this engagement to your app through the calling extensions SDK.
  6. Your app updates the placeholder engagement with the full details of the call.

See more details for these steps below.

Initiating a call

After a user connects your app to HubSpot, it will appear as an additional option when calling from a record. When users engage the "Call" option, they'll see the option to make the call using your app instead of the default HubSpot calling system.

See this knowledge article for more details on making calls from HubSpot.

calling_provider

The calling iframe

When the user chooses to make the call through their browser, an iframe is open to the URL specified in the calling settings for your app. This URL should point to a custom web application that will make the call through your calling service. Using the calling extensions SDK, your app will communicate with the HubSpot application. Messages from the HubSpot application will let your app know which number to call, and your app will be able to send messages for events such as the call ending or a user being logged out of your service.

calling_iframe

When building your app, there are some considerations to keep in mind:

  • You will need to have a web app that can be displayed inside of an iframe. Aside from displaying your application, HubSpot will not process any content of the iframe, so you can't set the iframe URL to a backend SIP service.
  • The design of the app should take into account that it will appear in an iframe window inside HubSpot, based on the height and width parameters set through the settings API. We've found that windows with a height of 600px and a width of 400px work best for the widest range of browser window sizes, including smaller screens.
  • You should make sure that error conditions can be displayed to the user inside the iframe. This is so your app can alert users about audio issues, network problems, or other errors.

Testing

While you're in the process of building your app, you can manually set the iframe URL for your browser by setting a localStorage value. This will allow you to set a localhost URL for local testing.

To set the value, open the developer tools for your browser and run the following JavaScript command in the developer console:

localStorage.setItem('LocalSettings:Sales:CallingExtensions', '{"name": "Example Calling app Title", "url": "https://myWidgetUrl/path/"}')

The name value will appear in the header of the calling widget, and the url will be the URL used for the iframe. When this item is set, the name you set will appear as an option for the call provider when you click the Call icon, and the calling widget will use the iframe url you set.

Logging the call in HubSpot

In HubSpot, calls are logged as engagement objects. These engagements are used to display the call details in the timeline of the associated CRM object. They're also used for HubSpot's built-in sales reporting.

When a call is made through your app, HubSpot will automatically create the base engagement object and send the ID of that engagement to your app through the calling extensions SDK. The ID will be passed to your app using the onEngagementCreated function. The basic details of the engagement will be set automatically by HubSpot, including the owner, type, and associations. You will need to update the details in the metadata of the engagement record to set the duration of the call, as well as any notes for the call in the body field. If there is a recording of the call, you can also set the recordingUrl, which will let HubSpot users play the recording when viewing the contact record in HubSpot.

See more details about updating engagements in our CRM engagements documentation.

For example:


{
  "engagement": {
    "timestamp": 1561953600000
    // A millisecond timestamp of the time of the call. This will default to the time that the call was initiated, but can be updated if needed.
  },
  "metadata": { // Details for the call
    "toNumber": "+1 (888) 482-7768",
    // The number that was called. Displayed as a string, with no further formatting.
    "durationMilliseconds": 38000,
    // The length of the call in milliseconds.
    "recordingUrl": "https://app.example.com/Recordings/callrecordpath",
    // A path to a recording of the call
    "body": "Call notes"
    // Details about the call, displayed as the description
  }
} 

The details above would result in an engagement that appears like the image below when viewed in HubSpot:

blob

See CRM engagements for more details on working with engagements.