Set up third-party calling in help desk (BETA)

Set up help desk support

To support connecting a phone number as a channel to your help desk, you’ll need to tell HubSpot how to fetch available numbers to be connected. To do this, register a webhook that'll return available numbers for the user. Whenever a HubSpot user wants to connect a device number from your extension to the help desk workspace, HubSpot will make a request to the registered webhook to get a list of available numbers that the user can select from. 

Webhook details

Request

To get the phone numbers available for channel connection, HubSpot will send a POST request to your registered webhook with the following request body parameters:

Use this table to describe parameters / fields
ParameterTypeDescription
appId
IntegerThe ID of the app for which this request was made. 
portalId
Integer

The ID of the HubSpot portal where the request originated from.

userId
Integer

The ID of the HubSpot user making the request.

The request will also include HubSpot signature headers to prove that the request came from HubSpot. Learn how to validate requests

Expected response schema

The endpoint that you provide to HubSpot should return a JSON-formatted response that provides a list of available phone numbers. Each phone number in the list should include the following fields:

Use this table to describe parameters / fields
ParameterTypeDescription
e164Number
StringThe phone number.
extension
String

While the webhook response schema accepts phone numbers with extensions, phone numbers with extensions aren't connected to the help desk at this time. Any phone numbers with extensions won't be selectable by the user.

friendlyName
String

HubSpot enforces a 24-character limit for friendly names for phone numbers. Any friendly name that's longer than 24 characters will be truncated to the first 24 characters by HubSpot.

For example, if your phone number is 18001231234, your extension is 1, and you want to label this number “My cell phone number”, the response you send back to HubSpot should be:

{ "phoneNumbers": [ { "e164Number": 18001231234 "extension": 1 "friendlyName": "My cell phone number" } ] }

Create and manage your webhook

The following endpoints are available to create and manage your webhook.

Create channel connection settings

To create channel connections settings, use the appId of your public app to make a POST request to crm/v3/extensions/calling/{appId}/settings/channel-connection, and include the following in your request body:

Use this table to describe parameters / fields
ParameterTypeDescription
url
StringThe target URL for this webhook.
isReady
Boolean

Determines whether this webhook is ready to be released to users of this extension. Learn more about isReady.

For example, if your endpoint URL was https://example.com/my-help-desk-service and you wanted to make it available immediately for HubSpot to call, the request body would be:

{"url":"https://example.com/my-help-desk-service","isReady":true}
Fetch existing channel connection settings

To fetch existing channel connection settings, use the appId of your public app to make a GET request to crm/v3/extensions/calling/{appId}/settings/channel-connection

If your channel connection settings were already set up correctly, the response will resemble the following:

{ "url": "https://example.com/my-help-desk-service, "createdAt": "2024-04-30 12:01", "updatedAt": "2024-04-30 12:01", "isReady": true }
Update channel connections settings

To update channel connections settings, make a PATCH request to crm/v3/extensions/calling/{appId}/settings/channel-connection, and include the following fields in your request body:

Use this table to describe parameters / fields
ParameterTypeDescription
url
StringThe target URL for this webhook.
isReady
Boolean

Determines whether this webhook is ready to be released to users of this extension. Learn more about isReady.

Delete existing channel connection settings

To delete existing channel connection settings, use the appId of your public app to make a DELETE request to crm/v3/extensions/calling/{appId}/settings/channel-connection

A successful DELETE call will result in a 204 No Content success status response code.

Understand the isReady flag

A third-party calling app is considered to support channel connection when the app has a webhook registered that's marked with isReady=true. If your app supports third-party connections, all users who have this app installed will have the option to select the app when they connect a number to their help desk.  Registering your webhook with isReady=false at first allows you to register the webhook and test it out without releasing it to all the users of your application immediately. To test your webhook’s help desk channel connection, you can override the isReady flag in-browser by setting local storage flag LocalSettings:Calling:supportsChannelConnection=true (see below). Once you have determined that the webhook’s help desk channel connection is working properly and you're ready for users to use your webhook, you can send a PATCH request to update the isReady flag to true and release the functionality to users. 

// To unlock your webhook for in-browser help desk channel connection testing, run this // command in your browser's dev tools console window.localStorage.setItem('LocalSettings:Calling:supportsChannelConnection', true);
User experience

Below are some examples of the user experience when choosing a calling provider for help desk. Learn more about the user experience.

  • If isReady=false and local storage flag is false: the app will appear greyed out for users when choosing a calling provider.

test-app-1

  • If isReady=false or true and local storage flag is true, the users will be able to select the app when choosing a calling provider.

test-app-2

 


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