Receive calls in HubSpot when using calling apps (BETA)

Overview

Please note: learn how to ungate your account for this beta. By using these instructions you agree to adhere to HubSpot's Developer Terms & HubSpot's Developer Beta Terms.

Developers using the Calling SDKcan now enable inbound calling within HubSpot. When a user receives and answers a call through your app in HubSpot, they can access call records directly in HubSpot, eliminating the need to switch back to the calling app. Calls are automatically logged in the Call Index Page where users can take real-time notes and review the call after it ends.

1. Install the latest version of Calling SDK

For npm, run:

npm i -s @hubspot/calling-extensions-sdk@latest

For yarn, run:

yarn add @hubspot/calling-extensions-sdk@latest

2. Set user availability

You can set the user's availability using on of the following events:

  • Via the initialized event:
const payload = { // Optional: Whether a user is logged-in isLoggedIn: boolean, // Optional: Whether a user is available for inbound calling isAvailable: boolean, // Optional: The desired widget size sizeInfo: { height: number, width: number } } extensions.initialized(payload);
  • Via the userAvailable event:
extensions.userAvailable();
  • Via the userUnavailable event:
extensions.userUnavailable();

3. Send message to notify HubSpot that an inbound call started

You will be able to send calling lifecycle events, such as callAnswered and callCompleted, in the same way it is done for outgoing calls.
const callInfo = { fromNumber: string, // Required: The caller's number toNumber: string, // Required: The recipient's number createEngagement: boolean, // Whether HubSpot should create an engagement for this call }; extensions.incomingCall(callInfo);
  • If you’ve set createEngagement to true, you can subscribe to onCreateEngagementSucceeded and onCreateEngagementFailed. It is recommended you do this so that you can enable your calling app to support custom objects. This will allow future integration into other areas of HubSpot. 
onCreateEngagementSucceeded(data) { const { /* A HubSpot created engagement id. */ engagementId: number, } = data; ... } onCreateEngagementFailed(data) { const { error: { message: string } } = data; ... }

4. Receive caller ID matches

  • You will be able to subscribe to onCallerIdMatchSucceeded and onCalledIdMatchFailed. This will enable you to receive contact matching data for the incoming call that previously had to be obtained via the Search API, and will solve its rate limitations. 
onCallerIdMatchSucceeded: data => { /* HubSpot has fetched caller id matches for this call. */ const { callerIdMatches: (ContactIdMatch | CompanyIdMatch)[]; } = data; } onCallerIdMatchFailed: data => { /* HubSpot has failed to fetch caller id matches for this call. */ const { error: { message: string } } = data; }
type ObjectCoordinates = { portalId: number; objectTypeId: string; objectId: number; } type ContactIdMatch = { callerIdType: 'CONTACT'; objectCoordinates: ObjectCoordinates; firstName: string; lastName: string; email: string; } type CompanyIdMatch = { callerIdType: 'COMPANY'; objectCoordinates: ObjectCoordinates; name: string; }

5. Navigate to a record page

Once you receive the caller ID matches, you can send HubSpot a message to navigate to a contact or company record page.

const data = { objectCoordinates: ObjectCoordinates // from onCallerIdMatchSucceeded }; extensions.navigateToRecord(data);

Once the call engagement is created, HubSpot will redirect to the contact page specified in the navigateToRecord payload and will sync with the SDK in the onReady event. You'll need to re-initialize the SDK using the engagement ID and show an incoming call within the iframe.

// Receive an engagementId for an existing inbound call type Payload = { engagementId: number | undefined } // Message indicating that HubSpot is ready to receive messages onReady(payload) { // Send initialized message to HubSpot to indicate that the call widget is also ready extensions.initialized(payload); if (payload.engagementId) { // Initialize calling state in the app for existing inbound call ... } ... }

In the following sections, preview how the incoming call feature will work in your calling app.

6. Ungate your account

To ungate your account for this beta, open your browser developer console from a HubSpot tab, and set the following:

localStorage['LocalSettings:Calling:supportsInboundCalling'] = true;

7. Set the provider

Before logging in to your calling app, you'll need to select the provider from your call settings:

  • In your HubSpot account, click the settings icon in the main navigation bar.
  • In the left sidebar menu, click General. Then, click the Calling tab at the top.
  • Click the Make and receive calls through dropdown menu, then select your calling app.

Callin apps- make calls

Once the preferred provider is selected, incoming calls will only be received through the selected provider. HubSpot will not support receiving incoming calls from multiple providers in this version. 

If you wish to change the provider for receiving calls, you'll have to go back to your call settings to make the change.

Please note: for outbound calls, you can continue to switch providersfrom the contact record.

Calling apps- call contact

 

8. Receive incoming calls

If you've not already set up an integration with any of the calling apps, click here to learn more.

  • Log in to your calling app through the call widget in HubSpot. The call widget can be accessed on the main navigation bar.

Calling apps- make a call

 

  • Set availability to e HubSpot to start receiving calls.

Calling apps- availability

 

  • Answer inbound calls from the call remote.
Please note: the behavior may vary slightly based on each calling apps' implementation.

answer-call-bananaphone

Once the call is completed, the inbound call gets logged in the Call Index page. Missed calls will also get logged here.

Please note: if the call widget is minimized but you're set to Available, you will still receive calls. If the call tab is closed during an ongoing call, the call will get disconnected.

9. Notify users

supportsInboundCalling is set to false by default, HubSpot displays a banner under each user's preferences dropdown.

banner

Once you have set your app settings using the calling settings endpoint, use the PATCH endpoint to change supportsInboundCallingto true. This will remove the banner, and lets HubSpot users know your calling app has completed all the steps necessary to receive inbound calls.

curl --request PATCH \ --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=DEVELOPER_ACCOUNT_API_KEY' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{"supportsInboundCalling":true}'

Once the above steps are complete, you can continue to extend the functionality of your calling app in HubSpot by setting up third-party calling in help desk (BETA).

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.