Supported products
Sales Hub -Professional Service Hub -Professional
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.
You'll need to create a public app if you want to define and register custom channels. The custom channel endpoints are not supported when building a private app.
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 the 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, you'll specify the configuration and capabilities for your channel:
- Specify the user-facing channel name as the value for the
name
field. - Provide a channel schema that includes an object that details the channel capabilities as the value for the
capabilities
field. - Certain fields are optional and can be updated later using a
PATCH
request:- You can also specify a
webhookUrl
for handling webhook events (e.g., handling updates to channel accounts). - You can include a
channelDescription
andchannelLogoUrl
that will appear in the setup flow for your channel. - Specify a redirect URL that users will be sent to after completing your setup flow with the
channelAccountConnectionRedirectUrl
field.
- You can also specify a
For example, the following request body provides an example channel schema with a set of basic channel capabilities:
{
"name": "My new custom channel",
"webhookUrl": "https://example.com/handle-new-outgoing-message-notification",
"capabilities": {
"deliveryIdentifierTypes": [],
"richText": ["HYPERLINK", "TEXT_ALIGNMENT", "BLOCKQUOTE"],
"allowInlineImages": false,
"allowOutgoingMessages": false,
"outgoingAttachmentTypes": ["FILE"],
"allowedFileAttachmentMimeTypes": ["image/png"],
"maxFileAttachmentCount": 1,
"maxFileAttachmentSizeBytes": 1500000,
"maxTotalFileAttachmentSizeBytes": 1500000,
"threadingModel": "INTEGRATION_THREAD_ID"
},
"channelAccountConnectionRedirectUrl": "https://example.com/path-back-to-your-connection-flow",
"channelDescription": "Respond to prioritized messages via our custom channel",
"channelLogoUrl": "https://example.com/logo.png"
}
The table below outlines each of the available parameters for the channel schema in the request body.
Parameter | Type | Description |
---|---|---|
name | String | The name of your channel, which will appear to users who install your app. |
webhookUrl | String | A valid URL where HubSpot will send webhook notifications of outgoing messages that should be sent using your channel. This field is not required when initially registering the channel. |
capabilities | Object | An object that specifies that the messaging content and recipient capabilities of your channel. Consult the table below for all supported fields for this object. |
channelAccountConnectionRedirectUrl | String | If you're creating a connection setup flow for your custom channel, this is the URL that HubSpot will point to when users click the option to install your app in the inbox or help desk connection setup in HubSpot. This field is not required when initially registering the channel. |
channelDescription | String | A string that will provide context under the channel when connecting it to HubSpot. This field is not required when initially registering the channel. See the section below on defining a setup flow for your custom channel. |
channelLogoUrl | String | A URL that points to a logo that appear for your channel when connecting it to HubSpot. This field is not required when initially registering the channel. See the section below on defining a setup flow for your custom channel. |
The table below outlines all available fields you can specify for the capabilities
field of your channel.
Parameter | Type | Description | Default |
---|---|---|---|
deliveryIdentifierTypes | Array | A required array that specifies the identifier types your channel supports for its senders and recipients. Consult the delivery identifier types table below for more info. | [] |
richText | Array | An optional array of supported rich text elements presented as options in HubSpot's message composer. Available values are "BLOCKQUOTE" , "BOLD" , "FONT_SIZE" , "FONT_STYLE" , "HYPERLINK" , "ITALIC" , "LISTS" , "TEXT_ALIGNMENT" , "TEXT_HIGHLIGHT_COLOR" , "TEXT_COLOR" , and/or "UNDERLINE" . If left unspecified, no rich text elements will be supported. | [] |
allowInlineImages | Boolean | Whether your channel allows inline images to be included in the message body. If set to true , HubSpot's message composer will present an Insert image option. | False |
allowOutgoingMessages | String | Whether your channel allows outgoing messages. You can set this field to true if you want your channel to be an "intake-only" message source. | False |
outgoingAttachmentTypes | Array | The types of attachments your channel supports (valid values are "FILE" and "QUICK_REPLIES" ). | [] |
allowedFileAttachmentMimeTypes | Array | The file MIME types that your channel supports for file attachments, if any. This defaults to a fairly permissive list of common text, image, audio, video, and archive files. | ["image/png", "text/plain", ...] |
maxFileAttachmentCount | Integer | The maximum number of file attachments permitted for a single message. | 0 |
maxFileAttachmentSizeBytes | Integer | The maximum individual file size permitted for a single attachment on a message, in bytes. | 0 |
maxTotalFileAttachmentSizeBytes | Integer | The maximum cumulative file size permitted for all attachments combined for a single message, in bytes. | 0 |
threadingModel | String | An enumeration denoting which threading model to use for messages. Values are: INTEGRATION_THREAD_ID and DELIVERY_IDENTIFIER . See the section below for more information. | INTEGRATION_THREAD_ID |
By default, the threading model of your custom channel is set to INTEGRATION_THREAD_ID
, where you're required to include an integrationThreadId
in every POST
message request. This ID will always be returned in the channelIntegrationThreadIds
property of the OUTGOING_CHANNEL_MESSAGE_CREATED
webhook event.
You can optionally set your threading model to DELIVERY_IDENTIFIER
, which is a good fit when there is only ever one open coversation between parties. If you set the threadingModel
to this value within the capabilities
object of your channel, you should not include an integrationThreadId
in any of your POST
message requests, because HubSpot will generate and manage its own threadIds
based on the following rules:
- A set of
deliveryIdentifiers
(e.g., email address, phone numbers, or other identifiers in the sender and/or recipients array of a message) may have a maximum of one active thread between these delivery identifiers at once. - Archived threads between that same set of participants are ignored.
- Outgoing messages can only be published on open threads, adn there can only be one thread between a specific set of participants at a time.
- Incoming messages can only be published to the same
threadId
if either of the following conditions are met:- The thread is already open.
- The thread was closed with the latest message activity occurring less than 24 hours ago, in which case the published incoming message will re-open the thread.
- The
channelIntegrationThreadIds
property within the payload of theOUTGOING_CHANNEL_MESSAGE_CREATED
webhook event will contain the value of thethreadId
that HubSpot created.
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:
Parameter | Type | Description |
---|---|---|
type | String | The format for an identifier of the sender or recipient. Much like a postal mail address, this identifier provides a well-defined format for sending or receiving messages to/from the individual contact. The following types are available:
|
value | String | The actual value of the delivery identifier (e.g., "support@example.com" for an HS_EMAIL_ADDRESS ). |
If you need to review or update your channel's configuration, you can send a GET
or PATCH
request to /conversations/v3/custom-channels?hapikey={YOUR_DEVELOPER_API_KEY}&appId={appId}&channelId={channelId}
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.
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
:
xxxxxxxxxx
{
"inboxId": "123",
"name": "My connected inbox",
"deliveryIdentifier": {
"type": "HS_EMAIL_ADDRESS",
"email": "jdoe@example.com"
},
"authorized": true
}
The table below provides details for each of the possible fields of a channel account:
Parameter | Type | Description |
---|---|---|
inboxId | String | The ID of the conversations inbox that you've connected your channel account to. You can retrieve a list of conversation inboxes with their associated IDs by using the conversations API. |
name | String | The friendly name that will appear to HubSpot users in their account. |
deliveryIdentifier | String | A required delivery identifier that should be associated with this channel account (e.g., a username or email address that uniquely identifies this channel account within your integrated messaging service). |
authorized | Boolean | By default this field is set to true , but if the account is no longer usable or accessible, you can update this to false to disable this channel account for your custom channel. |
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.
If you didn't specify a redirect URL for your connection flow when you initially registered your channel, you can update the behavior of your channel by making 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. You can also provide a channelDescription
and channelLogoUrl
if you didn't specify these fields previously or you want to update them.
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:
Parameter | Type | Description |
---|---|---|
accountToken | String | A shared object created in HubSpot's database that you'll use as an interim session token while the end user goes through the setup flow. Once they've provided all the parameters you'll need to connect their account, you'll use this token to make a PATCH request to /conversations/v3/custom-channels/{channelId}/channel-account-staging-tokens/{accountToken} , detailed in the section below this table. |
channelId | Number | The ID of your custom channel. |
inboxId | Number | The ID of the help desk or inbox that the HubSpot admin wants to connect your channel to. |
portalId | Number | The ID of the HubSpot account attempting to connect their account to your custom channel. |
redirectUrl | String | The HubSpot URL that you should send the user to when your flow and/or form submission is complete. |
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:
Parameter | Type | Description |
---|---|---|
accountToken | String | As detailed above, this is the same accountToken provided as a query parameter in the URL of your webpage when the user initiated the connection in their HubSpot account. This should be provided as a path parameter in the URL of your request. |
channelId | Number | The ID of your custom channel, provided as a path parameter in the URL of your request. |
accountName | String | This is a request body parameter that will act as a friendly name for the channel account that will appear in the inbox or help desk settings in the user's HubSpot account. |
deliveryIdentifier | DeliveryIdentifier | Provided as a request body parameter, the deliveryIdentifier that describes the address of the connected account. See the Delivery Identifiers section above for more details on how a deliveryIdentifier is structured. |
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:
Field | Type | Description |
---|---|---|
text | String | The plaintext content of your message. |
richText | String | An optional string that represents the HTML markup for the formatted text content of the message. |
channelAccountId | String | The ID of the channel account receiving the message. |
integrationThreadId | String | A required string based on the threadingModel you specified. If you specified the threadingModel for your channel to be INTEGRATION_THREAD_ID , then you'll need to provide the integrationThreadId for this field. If your threadingModel is set to DELIVERY_IDENTIFIER , this field must be set to null . |
integrationIdempotencyId | String | An optional string you can use as a unique-per-message idempotency ID, to ensure that multiple requests to publish this message don't result in duplicate copies of it being published. The idempotency ID is only unique in the context of a channel account: the same channel account cannot have two messages with the same idempotency ID. However, two different channel accounts can have messages that have the same idempotency ID. |
inReplyToId | String | An optional string you can use to reference the message ID of an existing message that this message is a direct reply to. |
messageDirection | String | A required string that should be set to "INCOMING" . |
senders | Array | A list of messages senders. Each sender should be provided as an object with two fields: a deliverIdentifier , detailed above, and a name , which is an optional string that serves as a friendly name for the sender. |
recipients | Array | A list of intended recipients. Each recipient should be provided as an object with two fields: a deliveryIdentifier , detailed above, and a name , which is an optional string that serves as a friendly name for the recipient. |
timestamp | String | An optional timestamp, in ISO8601 format, that specifies when the message was received. If omitted, this value will default to the time you publish the message to HubSpot. |
attachments | Array | An optional list of message attachments. |
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 AP, 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:
Parameter | Type | Description |
---|---|---|
type | String | A required string that must be set to "FILE" . |
fileId | String | The HubSpot file ID for the uploaded file that the attachment will reference. |
fileUsageType | String | An enumeration used to render an appropriate preview of the file attachment. Available values are "STICKER" , "VOICE_RECORDING" , "IMAGE" , "AUDIO" , or "OTHER" . |
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:
Parameter | Type | Description |
---|---|---|
type | String | A required string that must be set to "QUICK_REPLIES" . |
quickReplies | Array | A list of one or more predefined responses. Each quick reply is an object that should include the following fields:
|
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:
xxxxxxxxxx
{
"type": "UNSUPPORTED_CONTENT"
}
To handle outgoing messages sent from HubSpot using your custom channel, HubSpot will send a payload as a POST
request to the webhookUrl
that you specified when you first registered your custom channel.
The payload of the request that HubSpot sends will include a type of OUTGOING_CHANNEL_MESSAGE_CREATED
. The table below provides a full reference on all fields included in the body of the webhook event:
Parameter | Type | Description |
---|---|---|
type | String | A string that specifies the webhook event type, which will be "OUTGOING_CHANNEL_MESSAGE_CREATED" . |
portalId | String | The ID of the HubSpot account from which the message was sent. |
channelId | String | The ID of the custom channel. |
eventTimestamp | String | When the event occurred, represented as an ISO8601 timestamp. |
message | String | An object that provides details about the outgoing message. Each of the fields of this message are detailed in the message table below. |
eventId | String | Unique reference to a specific message over a given channel used for debugging. |
channelIntegrationThreadIds | Array | The value for this field is based on the threading model you specified for your channel. The array includes an integrationThreadId that was sent if you opted for a threadingModel of INTEGRATION_THREAD_ID for your channel. If you specified a threadingModel of DELIVERY_IDENTIFIER , this array will include a HubSpot-generated value. |
The message
object in the webhook payload contains the following fields:
Field | Type | Description |
---|---|---|
id | String | A unique message ID |
type | String | A string that's hard-coded to "MESSAGE" . |
channelId | String | The ID of your custom channel. |
channelAccountId | String | The ID of the channel account receiving the message. |
conversationsThreadId | String | The ID of the thread in the conversations inbox that includes this message. |
createdAt | String | An ISO8601 timestamp representing the time when the user hit Send from within the HubSpot message composer. |
createdBy | String | A string representing the actorId of the HubSpot user who sent the message. |
senders | Array | A list of messages senders. Each sender is provided as an object with three fields: an actorId string, a deliverIdentifier , detailed above, and a name , which is a string that serves as a friendly name for the sender. |
recipients | Array | A list of intended recipients. Each recipient is provided as an object with three fields: an actorId string, a deliveryIdentifier , detailed above, and a name , which is an optional string that serves as a friendly name for the recipient. |
text | String | The plaintext content of your message. |
richText | String | An optional string that represents the HTML markup for the formatted text content of the message. |
direction | channelAccountId | "OUTGOING" |
inReplyToId | String | An optional string you can use to reference the message ID of an existing message that this message is a direct reply to. |
truncationStatus | String | "NOT_TRUNCATED" |
status | String | "SENT" |
attachments | Array | An optional list of message attachments. |
Whenever a channel account is connected, 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 succeeded, or if the channel is later modified or deleted.
The payload of the request that HubSpot sends will includes the fields listed in the table below. The event's type will be provided in the type
field:
CHANNEL_ACCOUNT_CREATED
: triggered when an admin successfully connected a custom channel to an inbox or help desk in their HubSpot account.CHANNEL_ACCOUNT_UPDATED
: triggered when a HubSpot user updates a channel account that uses one of your connected custom channels.CHANNEL_ACCOUNT_PURGED
: triggered when a HubSpot user deletes a channel account that uses one of your connected custom channels.
Parameter | Type | Description |
---|---|---|
type | String | A string that specifies the webhook event type. |
portalId | String | The HubSpot portal ID associated with the custom channel. |
channelId | String | The channel ID of your custom channel. |
eventTimestamp | String | When the event occurred, represented as an ISO8601 timestamp. |
channelAccountId | String | The ID of the custom channel account. |
channelAccountDeliveryIdentifier | String | The delivery account identifier that's associated with the channel account. |
To archive a custom channel, make a DELETE
call to /conversations/v3/custom-channels/{channelId}
using the ID of the channel you want to archive as the channelId
.
If successfully archived, you'll receive a response of 204 No content
.