Overview

Calling Extension SDK enables an integrated end user calling experience for both outbound and inbound calling.

The soft phone widget is rendered inside HubSpot CRM and a lightweight wrapper around HTML5 postMessage API facilitates cross-origin communication between a soft phone widget and HubSpot.

Typical message flow

Loading the widget

The following messages are exchanged when a calling widget is instantiated -

[HubSpot] Sends a SYNC message
[SoftPhone] Sends SYNC_ACK message
[SoftPhone] Sends INITIALIZED message with login state and optionally widegt size

After this point, the messages can be exchanged between the soft phone widget and HubSpot.

Note that the SYNC message sent repetidly until it receives a response from the iFrame to account for slow loading of

Outbound call

The following messages are exchanged when user initiates a call -

[HubSpot] Sends DIAL_NUMBER message with phone_number to dial
[SoftPhone] Sends the OUTGOING_CALL_STARTED message with the phone number that is dialed
[SoftPhone] Sends the CALL_ANSWERED message
[SoftPhone] Sends DATA message with engagementId once the engagement is created
[SoftPhone] Sends the CALL_ENDED message

Incoming call

The following messages are exchanged for an incoming call -

[SoftPhone] Sends the INCOMING_CALL message with caller information
[SoftPhone] Sends the CALL_ANSWERED message
[SoftPhone] Sends DATA message with enagegementId once the engagement is created
[SoftPhone] Sends the CALL_ENDED message

Getting Started

Register you calling extensions

TBD - Register the calling application and the calling extensions

Integrate Calling Extensions SDK

Get the Calling Extension SDK

Download the SDK using npm or yarn

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

Using the Calling Extension SDK

The Calling Extension SDK exposes a simple API for HubSpot and a Soft Phone to exchange messages. The messages are sent as a method call 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: {
    onDialNumber: event => {},
    onVisibilityChanged: event => {}
  }
};

const CallingExtensions = new CallingExtensions(options);

Sending the messages to HubSpot

The messages are sent to HubSpot through method calls. Following is a list of messages that can be sent to HubSpot

INITIALIZED

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
    widgetSize: {
        height: number,
        width: number
    }
}
CallingExtensions.initialized(payload);

LOGGED_IN

Sends a message indicating that user has logged in
```
CallingExtensions.userLoggedIn();
```
LOGGED_OUT

Sends a message indicating that user has logged out
```
CallingExtensions.userLoggedOut();
```
INCOMING_CALL

Sends a message to notify HubSpot of an incoming call.

Note that the incoming calling is not yet supported across HubSpot. If the widget is active, this method will ensure that the widget is made visible.
```
const callInfo = { phoneNumber: string };
CallingExtensions.incomingCall(callInfo);
```
OUTGOING_CALL_STARTED

Sends a message to notify HubSpot that an outgoing call has started.
```
const callInfo = { phoneNumber: string };
CallingExtensions.outgoingCall(callInfo);
```
- CALL_ANSWERED
Sends a message to notify HubSpot that an outgoing call is being answered.
```
CallingExtensions.callAnswered();
```
- CALL_ENDED
Sends a message to notify HubSpot that the call has ended.
```
CallingExtensions.callEnded();
```

RESIZE_WIDGET

Sends a message to resize the iFrame

const newSize = { width: number, height: number };
CallingExtensions.resizeWidget(newSize);

CALL_DATA

Sends a message transferring the engagementId

const data = {
  // engagementId of the enagagement created for this call (inbound or outbound)
  engagementId: number
};
CallingExtensions.sendCallData(data);

Handling a message sent from HubSpot to the soft phone

onDialNumber

Handler for the dial number event.

  onDialNumber(data) {
      const { phoneNumber } = data;
      ...
  }

Visibility Change

Handler for visibility change event.

  onVisibilityChanged(data) {
      const { isMinimized, isHidden } = data;
      ...
  }

Running the demo Calling Extension Widget project

The calling extensions are enabled for any portal that is starter or above.

Build the demo widget project

# install npm build dependencies and build the demo project
cd /demo
npm i
npm run build

Serve the demo widget

Easiest way to serve the demo widget is through running http-serve.

npm install -g http-serve 
# Create a temperory certificate to use for HTTPS
openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
# cd into the demo folder
cd /demo
# Run the http server
http-serve -S -C cert.pem -o

Load the demo page in chrome and accept the invalid cert exception

Add local storage override for calling extensions

The calling widget settings are added during application creation in the developer portal. The following localstorage override is available for testing purposes -

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

anthony-nardi / calling-extensions-sdk