Calling Extensions SDK

The Calling Extensions SDK allows apps to provide a custom calling option to HubSpot users directly from a record in the CRM. 

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 is where your app appears to HubSpot users and is configured using the calling settings endpoints.

For more information on the in-app calling experience, review this knowledge base article. 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.

Please 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 appear 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 ended.
  • HubSpot telling your app the placeholder engagement ID 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. If you don't already have a HubSpot developer account, sign up for one here.

Once you've configured the calling settings for your app, which is a one-time task, these settings will apply for all users connecting the app to their HubSpot account. Review the Endpoints tab for details 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 icon 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.

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

Learn more about making calls from HubSpot

calling_provider

When the user chooses to make the call through their browser, an iframe opens 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 because HubSpot will not process any content of the iframe, so you can't set the iframe URL to a backend SIP service.
  • The height and width parameters set through the settings API will determine the size of the iframe. 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 appear 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. HubSpot will set the engagement's basic details, 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.

Check out more details about updating engagements in our CRM engagements documentation.

For example:

JSON
//
{
  "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:

calling-sdk-engagement

Review CRM engagements for more details on working with engagements.


Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.