Custom channels (BETA)

If you have a Sales Hub Enterprise or Service Hub Enterprise account, you can create custom channels to build a bridge between an external message service and HubSpot's inbox or help desk features. You can then publish your custom channel app in the HubSpot App Marketplace for other HubSpot admins to install and use in their own accounts.

To get started, you'll need to create a public app that you'll use to register your custom channel with HubSpot, then handle incoming and outgoing messages to an inbox.

You can follow the instructions in this article to create your public app. When configuring the scopes for your app on the Auth tab, ensure that your app requests the following scopes:

• conversations.custom_channels.read: this scope allows you to access to read messages and threads that your custom channel has already published to HubSpot.
• conversations.custom_channels.write: this scope allows you to publish messages to HubSpot.
• conversations.read: this scope allows you to retrieve a list of conversation inboxes in an account using the Conversations BETA API, so that you can connect channel accounts to specific inboxes.

Once you've created your app, take note of the following app details that you'll use to identify your app when making requests to the Custom Channels API endpoints.

• App ID
• Client ID
• Client secret

After creating your app, you can create your custom channel in HubSpot, using your HubSpot Developer API Key, and your App ID of the app you just created.

To register your channel, make a POST request to https://api.hubapi.com/conversations/v3/custom-channels?hapikey={YOUR_DEVELOPER_API_KEY}&appId={appId}.

In the body of your request, provide a channel schema that includes an object that details the channel capabilities. 

For example, the following request body provides an example channel schema with a set of basic channel capabilities:

The table below outlines each of the parameters required for the channel schema in the request body.

The table below outlines all available fields you can specify for the capabilities field of your channel.

The deliveryIdentifierTypes field specified within the channelCapabilities of your channel specifies an array of delivery identifiers.

A delivery identifier is an object that includes a type and value, that describes sender or recipient delivery details:

If you need to review or update your channel's configuration, you can send a GET or PATCH request to the same endpoint above using the same channel schema. PATCH requests also accept partial-update requests.

After you've created your custom channel, the next step is to allow specific channel accounts to be connected to a user's HubSpot account, so that messages can be sent and received.

Channel account connection for specific accounts

If you're developing a custom channel for your own business, or building a specific integration on behalf of a client, you can connect channel accounts directly to a HubSpot account. You'll need to have direct administrative access to the account or have an app installed in an account that's authorized the conversations.read scope.

When a HubSpot user installs your custom channel app in their account, a request will be sent to your custom channel's Redirect URL, which contains an authorization code that can be used to request an OAuth token for accessing that user's HubSpot account and its associated data. For more information on how OAuth works, check out this article.

Once you've obtained an OAuth access token using the authorization code, you can use this OAuth access token to send requests to HubSpot to connect specific channel accounts.

To connect a specific channel account, make a POST request to /conversations/v3/custom-channels/{channelId}/channel-accounts, where the channelId is the channel ID that you've registered.

The request body below provides an example channel account schema for an inbox ID of 123: 

The table below provides details for each of the possible fields of a channel account:

If you're developing a custom channel integration that you want to distribute to multiple customers via the HubSpot marketplace, you can register an account connection flow that will appear within the in-app HubSpot inbox or help desk connection flow.

The screenshot below showcases how an example custom channel called HuddleHub would appear in the help desk connection flow in HubSpot. Your app's name, description, and logo from your public app settings will appear as part of the custom channel option that users can click to connect.

Any account that installs your app can click the associated option to authorize their credentials with any third-party service you're integrating with (if applicable), then proceed to connect that account to HubSpot. When users click the associated option in HubSpot, a pop-up window will open and load a webpage that allows them to provide their credentials. You'll need to host this webpage and any associated backend services yourself.

The screenshot below provides a minimal example of what this dialog box looks like and includes some debugging information based on the query parameters that HubSpot includes in the URL. When designing your own page, you should optimize it for a 600px by 600px window, and provide a user-friendly method (e.g., a form) to provide any account details and delivery identifier information you'll need to connect their account.

To register the behavior of your custom channel account connection with a HubSpot account that's installed your app, you'll make a PATCH request to /conversations/v3/custom-channels/{channelId}. In the body of your request, set the channelAccountConnectionRedirectUrl property to the URL that you want HubSpot to navigate to when users click your custom channel in the connection flow.

Once clicked, HubSpot will open a new window with the URL you specified, and append the following query parameters that you can use to authenticate with a third-party service, or for any other custom behavior you might need to wire up based on the user's HubSpot account, inbox, channel, or user information:

Once you've collected the user's information in your page (e.g., using a form to collect each of the required parameters) and the user confirms their input by clicking a submission button, you can make a PATCH request to /conversations/v3/custom-channels/{channelId}/channel-account-staging-tokens/{accountToken} and provide the following parameters in your request:

Once you've made the PATCH request and gotten a successful response, you can redirect the user back to the redirectUrl detailed above and close the pop-up window.

The user will then see a success screen in their HubSpot account:

When a channel account that uses your custom channel receives a message in the external message service (e.g., a user gets a new direct message in their social account's inbox), you'll want to ensure that the message gets published to HubSpot, which will log it into the HubSpot CRM and the associated conversations inbox.

To publish a received message to HubSpot, make a POST request to /conversations/v3/custom-channels/{channelId}/messages, where the channelId should be the channel ID that you previously registered.

The body of your request can include the following fields:

Several message attachment types are currently available: files, quick replies, as well as a catch-all type for unsupported file attachments.

File attachments can be uploaded using HubSpot's files API, and the resulting file ID can be used to reference the file contents when publishing incoming messages to HubSpot.

Consult the table below for details on how to structure a message attachment referencing an uploaded file:

Some chat services, such as Facebook Messenger, present suggested options as "quick replies" to users, allowing them to select from a predefined list of response messages. HubSpot supports this functionality by providing the ability to include quick replies as an attachment to your message.

Consult the table below on how to structure a message attachment that includes a list of quick replies:

These attachments are used to represent attachment types included in the original message that HubSpot cannot recognize.

For example, if a channel account on the messaging platform you're connecting to HubSpot via your channel receives a message that includes an attachment not listed in this article, and you want users viewing the message in their HubSpot account to know there was an attachment they might want to view directly on the messaging platform, you could use this attachment type when publishing the message to HubSpot.

To specify an unsupported content attachment, the attachment should be specified as follows:

The message object in the webhook payload contains the following fields:

Whenever a channel account is updated or deleted, HubSpot will send a payload as a POST request to the webhookUrl that you specified when you first registered your custom channel. This can be useful for cases where you want to take an action such as notifying your users that their connection to HubSpot has been modified or deleted.

The payload of the request that HubSpot sends will include a type of CHANNEL_ACCOUNT_UPDATED. The table below provides a full reference on all fields included in the body of the webhook event:

The payload of the request that HubSpot sends will include a type of CHANNEL_ACCOUNT_PURGED. The table below provides a full reference on all fields included in the body of the webhook event: