Overview

Calling Extensions SDK enables 3rd party VOIP providers or enterprise calling systems seamlessly integrate their CTI (referred to as call widget) with HubSpot for outbound calling. Call Widget is rendered inside HubSpot UI and a lightweight wrapper around HTML5 postMessage API facilitates cross-origin communication between the widget and HubSpot.

Getting Started

1. Create a HubSpot application and setup a test portal
2. Integrate the Calling Extensions SDK with your call widget.
3. Test your app in local environment
4. Get your app ready for production
5. Publish your app to the HubSpot marketplace.

Integrate Calling Extensions SDK

Get the Calling Extensions SDK

Download the SDK using npm or yarn

npm install -s @hubspot/calling-extensions-sdk

Running the demo Calling Extensions Widget project

Run the demo widget project

# install npm build dependencies and start the demo project
# The following commands will automatically start the browser on the demo page.
cd /demo
npm start

Launch the demo widget from HubSpot

Navigate to the a contact/company page in HubSpot and launch calling, the demo widget should load inside an iFrame.

Using the Calling Extensions SDK

The Calling Extensions SDK exposes a simple API for HubSpot and a Soft Phone to exchange messages. The messages are sent through methods exposed by SDK and received through eventHandlers.

Create an instance

import CallingExtensions from "@hubspot/calling-extensions-sdk";

const options = {
  // Whether to log various inbound/outbound messages to console
  debugMode: true | false,
  // eventHandlers handle inbound messages
  eventHandlers: {
    onReady: () => {
      /* HubSpot is ready to receive messages. */
    },
    onDialNumber: event => {
      /* Dial a number */
    },
    onEngagementCreated: event => {
      /* HubSpot has created an engagement for this call. */
    },
    onVisibilityChanged: event => {
      /* Call widget's visibility is changed. */
    }
  }
};

const extensions = new CallingExtensions(options);

Sending the messages to HubSpot

:warning: Wait for the onReady event before sending sending any messages to HubSpot.

// Sends a message indicating that the soft phone is ready for interaction.
const payload
{
  // Whether a user is logged-in
  isLoggedIn: true|false,
  // Optionally send the desired widget size
  sizeInfo: {
    height: number,
    width: number
  }
}

extensions.initialized(payload);

// Sends a message indicating that user has logged in
// This message is only needed when user isn't loged in when initialized
extensions.userLoggedIn();

// Sends a message indicating that user has logged out
extensions.userLoggedOut();

// Sends a message to notify HubSpot that an outgoing call has started.

const callInfo = {
  phoneNumber: string, // optional unless call is initiated by the widget
  createEngagement: true // whether HubSpot should create an engagement for this call
};
extensions.outgoingCall(callInfo);

extensions.callAnswered();

// Sends a message to notify HubSpot that the call has ended.
// After receiving the call ended event, the user can navigate away, can close the call widget.
extensions.callEnded();

// Sends a message to notify HubSpot that the call has completed.
// After receiving the call completed event, HubSpot will
//   1) insert the engagement into the timeline
//   2) set the default associations on the engagement
//   3) closes the the widget unless `hideWidget` is set to false.
const data = {
  engagementId: number,
  hideWidget: boolean // (optional) defaults to true
};
extensions.callCompleted(data);

Receiving messages from HubSpot

// Message indicating that user has triggered an outbound call
onDialNumber(data) {
  const {
    /* The phone nubmer to dial */
    phoneNumber: string,
    /* The id of the logged in user.   */
    ownerId: number,
    /* HubSpot object Id of the phoneNumber */
    objectId: number,
    /* HubSpot  object type of the phoneNumber */
    objectType: CONTACT | COMPANY
   } = data;
    ...
  }

  // Message indicating that HubSpot has created
  onEngagementCreated(data) {
    const {
      /* A HubSpot created engagement id. */
      engagementId: number,
    } = data;
      ...
  }

  // Message indicating if user has minimized/hide the call widget
  onVisibilityChanged(data) {
    const { isMinimized, isHidden } = data;
    ...
  }

 // Default handler for events.
 defaultEventHandler(event) {
   console.info("Event received. Do you need to handle it?", event);
 }

Typical message flow between the call widget and HubSpot

Initializing the call widget

The following messages are exchanged when a call widget is instantiated.

Once the widget iFrame is created, Hubspot send the SYNC message to the widget after iFrame is loaded and repetedly send this message until it receives the SYNC_ACK response from the widget. If the SYNC_ACK response isn't received within 30 seconds, the widget is marked as failed. Note that sending SYNC/SYNC_ACK messages are handled by the framework. Once the widget and host page are synchronized, the frameworks triggers the ready event.

The call widget should wait for the ready event from the framework and send the initialized event to HubSpot. At this point, the messages can be exchanged between the call widget and HubSpot.

Outbound call

The following messages are exchanged when user initiates a call. Hubspot ensures the call widget is logged in before sending in a dial number event - if the widget is not logged in, an alert is shown in HubSpot's UI.

Here is description of events:

1. Dial number - HubSpot sends the dial number event.
2. Outbound call started - Widget notifies HubSpot when the call is started.
3. Create engagement - HubSpot creates an engagement with minimum information if requested by the widget.
4. Engagement created - HubSpot created an engagement.
5. EngagementId sent to Widget - HubSpot sends the engagementId to the widget.
6. Call ended - Widget notifies when call is ended.
7. Call completed - Widget notifies when user is done with the widget user experience.
8. Update engagement - Widget fetches the engagment by the engagementId, merges and updates the engagement with additional call details. Call engagement overview, Docs on updating the engagement

Test your app in local environment

While you're in the process of building your application, 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:

// Add the following localstorage override for demo widget
localStorage.setItem(
  "LocalSettings:Sales:CallingExtensions",
  '{"name": "Demo widget", "url": "https://localhost:9025/"}'
);

The name value will be the title that appears in the header of the calling widget, and the url will be the URL used for the iframe. While 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.

Get your app ready for production

In order to launch the calling extensions iFrame for end users, HubSpot requires the following iFrame parameters.

{
  name: string /* The name of your calling service to display to users. */,
  url: string  /* The URL to your phone/calling UI, built with the Calling Extensions */,
  width: number /* The iFrame's width */,
  height: number /* The iFrame's height */,
  isReady: boolean /* Whether the widget is ready for users (default=true) */
}

Using your favorite API tool (postman/etc.), send this payload to our settings API. Please get the APP_ID of your calling widget application and your dev portal's HUBSPOT_API_KEY

# Example payload to add the call widget app settings
curl --request POST \
  --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=HUBSPOT_API_KEY' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"name":"demo widget","url":"https://mywidget.com/widget","height":600,"width":400,"isReady":true}'

# Note that this endpoint also support GET and DELETE

The isReady flag indicate whether the widget is ready for production. This flag should be set to false during testing. Note that this flag (or any other field) can be overwritten through localStorage.

/* Override the isReady flag for "Demo widget" */
localStorage.setItem(
  "LocalSettings:Sales:CallingExtensions",
  '{"name": "Demo widget", "isReady": true}'
);

Publish application to the HubSpot marketplace

The final step once your app is setup is to list in the HubSpot marketplace. You can find more details here . You can also choose to not list in the marketplace if this application is for your internal use only.

FAQs

App