The HubSpot Calling Extensions SDK provides a standardized method for integrating third-party calling applications directly into the HubSpot user interface. It allows sales and service representatives to make and receive calls from within the CRM, automatically logging call activities against contact records. Unlike a simple data sync via API, this SDK creates a native-feeling user experience, embedding your calling provider’s functionality into an iframe within the contact timeline and call interface.
Using the SDK is the required approach for building a calling integration that appears in the HubSpot App Marketplace. It ensures a consistent user experience and handles the critical communication between your application and the HubSpot frontend. This method centralizes call control, logging, and outcome tracking, which is essential for accurate reporting and sales performance monitoring. Without it, users are forced to switch between their phone system and HubSpot, leading to lost data and inefficient workflows.
This guide details the technical steps required to implement the Calling Extensions SDK. We will cover creating the necessary HubSpot developer app, initializing the SDK, handling call state messages, logging call data to the CRM, and troubleshooting common issues. Following this process ensures your integration is robust, user-friendly, and correctly interacts with the HubSpot platform. For complex implementations or if you require assistance, our HubSpot CRM setup & automation services can provide expert guidance.
What is the HubSpot Calling Extensions SDK?
The HubSpot Calling Extensions SDK is a JavaScript library that facilitates communication between your external calling application and the HubSpot CRM frontend. When a user initiates a call from a contact record in HubSpot, HubSpot loads your application in an iframe and uses the SDK to pass messages back and forth. These messages include commands to initialize the call, updates on call status, and data to be logged upon call completion. The primary function of the SDK is to standardize this interaction, making it possible for numerous calling providers to integrate seamlessly.
This SDK is fundamentally different from using HubSpot's public APIs to simply log a completed call. While the API can create a call activity record after the fact, the SDK enables a real-time, interactive experience. It allows HubSpot to control your application's widget size, pass contact information to your dialer, and receive events as they happen, such as when a call is answered or ends. This creates a deeply integrated workflow that feels like a native HubSpot feature.
By implementing the SDK, you enable features like click-to-call on contact records, automatic display of your calling widget, and post-call disposition selection directly within HubSpot. This reduces manual data entry for sales and service teams, improves data accuracy, and provides managers with real-time insight into calling activities. A successful implementation relies on correctly handling the postMessage events that form the core of the SDK's communication protocol. HubStack has extensive experience building these types of integrations for clients with unique telephony needs.
Prerequisites: What You Need Before You Start
Before writing any code, you must have several key assets in place. First, a HubSpot developer account is mandatory. This is separate from a standard HubSpot user account and provides access to the tools needed to create and manage applications. You can create one for free from the HubSpot developers portal. This account will be the owner of the application you create to house your integration's settings.
Second, you need a functioning calling application that can be embedded in an iframe. This application must be accessible via a secure HTTPS URL, as HubSpot will not load content over HTTP. Your application is responsible for handling the actual telephony—making, receiving, and managing the call audio. The HubSpot SDK does not handle the call itself; it only orchestrates the communication between your app and the CRM. Your application must also be capable of executing JavaScript and interacting with the browser's postMessage API.
Finally, you need a clear understanding of your calling provider's capabilities. You must know how to programmatically initiate a call, mute, hang up, and access call metadata like duration, recording URLs, and call outcomes from within your application's code. This information will be crucial for logging accurate data back into HubSpot. If your integration requires ongoing support, consider a HubSpot support & maintenance plan to ensure its long-term stability.
Creating and Configuring Your HubSpot App
The first step in the implementation process is creating an app in your HubSpot developer account. Navigate to 'Apps' in your developer portal and click 'Create app'. Give your app a descriptive name and configure its basic information. The most critical part of this process is the 'Calling' tab in the app settings. Here, you will enable the calling features and provide the necessary URLs for your application.
Within the Calling settings, you must specify the 'Calling app URL'. This is the HTTPS endpoint for the main page of your calling application—the page HubSpot will load into the iframe. You will also need to define the width and height of your widget. These dimensions determine the size of the iframe when it is rendered by HubSpot. It is important to test these dimensions to ensure your app's UI is usable within the given space.
Next, you need to define the CRM card for your app. Even though the primary interface is the calling widget, a CRM card is required for the integration to be complete. Go to the 'CRM Cards' section of your app settings and configure a new card. You can fetch data from an external source or simply display static content. Finally, install your developer app into a HubSpot test portal (a sandbox or a standard portal you can use for testing) to get the necessary permissions and begin development.
Initializing the SDK in Your Calling Application
Once your app is configured in HubSpot, you must integrate the Calling Extensions SDK into your application's frontend code. The SDK is a JavaScript file provided by HubSpot. You include it in your application using a script tag. Once the script is loaded, it exposes a global `HubSpotCallingExtensions` object that your code will use to communicate with the HubSpot parent window.
Your application's first task upon loading in the iframe is to send an `INITIALIZED` message to HubSpot. This message signals that your app has loaded successfully and is ready to receive commands. The message must include a `isLoggedIn` boolean property, indicating whether the user is authenticated with your calling service. If `isLoggedIn` is false, HubSpot can display a login view for your app.
After initialization, your app must listen for `message` events on the `window` object. HubSpot will send JSON-formatted messages to your iframe to trigger actions. The most important initial message to handle is the `DIAL_NUMBER` command. This message is sent when a user clicks a 'call' button in HubSpot and includes the phone number to be dialed and details about the associated CRM object. Your application should parse this message and use the provided number to initiate an outbound call through your telephony provider.
Mapping Call Data to HubSpot CRM Properties
A core function of the integration is to log call activity back to the HubSpot CRM automatically. When a call is completed, your application must send a `CALL_ENDED` message to HubSpot. This message contains a payload of data about the call that HubSpot uses to create a call engagement on the contact's timeline. This eliminates the need for manual logging by the user.
The `CALL_ENDED` payload must include the `engagementId` that was provided by HubSpot in the initial `DIAL_NUMBER` message. This ID links the logged call back to the correct engagement placeholder. You must then map the data from your calling system to the appropriate HubSpot properties. This includes the call duration, a link to the call recording, the call outcome or disposition, and any notes taken by the agent during the call.
Correctly mapping these fields is critical for reporting and automation in HubSpot. For example, the `disposition` field should be mapped to the HubSpot call disposition property, which is a unique GUID for each outcome. You can fetch the available disposition GUIDs from the Engagements API. Failing to map these properties correctly will result in incomplete data and render reports useless. Review the table below for a summary of key fields and their corresponding HubSpot properties.
| Your Application Data | HubSpot Property in Payload | Description | Data Type |
|---|---|---|---|
| Call notes or summary | body | The notes taken by the rep during the call. | String |
| Unique call outcome ID | disposition | The GUID of the HubSpot call disposition (e.g., 'Connected'). | String |
| Call duration in milliseconds | durationMilliseconds | The total length of the call. | Number |
| External system's call ID | externalId | The unique identifier for the call in your system. | String |
| Public URL for recording | recordingUrl | A link to the audio recording of the call. | String |
| Call status (e.g., COMPLETED) | status | The final status of the call. Must match a valid HubSpot status. | String |
Troubleshooting Common SDK Implementation Errors
Developers often encounter a few common issues when first implementing the Calling SDK. The most frequent problem is a failure to communicate between the iframe and the parent HubSpot window. This is often caused by not sending the `INITIALIZED` message correctly or failing to set up a `message` event listener. Use your browser's developer tools to inspect console logs and monitor the postMessage events being sent and received.
Another common pitfall involves authentication and `isLoggedIn` status. If your app sends `isLoggedIn: false`, you must provide a way for the user to log in within the iframe. If this flow is broken, the user will be stuck and unable to use the calling feature. Ensure your login process works correctly within the confines of the iframe and that upon successful login, you re-initialize the extension with `isLoggedIn: true`. Our team at HubStack frequently debugs these exact issues for clients.
Finally, data logging issues are prevalent. If calls are not appearing on the contact timeline, verify that your `CALL_ENDED` message contains the correct `engagementId` that HubSpot sent with the `DIAL_NUMBER` command. Also, check that the `disposition` GUIDs are correct and that the `status` string matches one of HubSpot's accepted values (e.g., 'COMPLETED', 'NO_ANSWER'). Incorrect or missing data in this payload is the primary reason for logging failures. For persistent issues, a full code review is often necessary, something covered in our HubSpot technical SEO and integration audits.