Skip to main content

Supported products

Requires one of the following products or higher.

  • 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 and channelLogoUrl 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.

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 available parameters for the channel schema in the request body.

ParameterTypeDescription
nameStringThe name of your channel, which will appear to users who install your app.
webhookUrlStringA 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.
capabilitiesObjectAn object that specifies that the messaging content and recipient capabilities of your channel. Consult the table below for all supported fields for this object.
channelAccountConnectionRedirectUrlStringIf 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.
channelDescriptionStringA 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.
channelLogoUrlStringA 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.

ParameterTypeDescriptionDefault
deliveryIdentifierTypesArrayA 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.[]
richTextArrayAn 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.[]
allowInlineImagesBooleanWhether 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
allowOutgoingMessagesStringWhether 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
outgoingAttachmentTypesArrayThe types of attachments your channel supports (valid values are "FILE" and "QUICK_REPLIES").[]
allowedFileAttachmentMimeTypesArrayThe 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", ...]
maxFileAttachmentCountIntegerThe maximum number of file attachments permitted for a single message.0
maxFileAttachmentSizeBytesIntegerThe maximum individual file size permitted for a single attachment on a message, in bytes.0
maxTotalFileAttachmentSizeBytesIntegerThe maximum cumulative file size permitted for all attachments combined for a single message, in bytes.0
threadingModelStringAn 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 the OUTGOING_CHANNEL_MESSAGE_CREATED webhook event will contain the value of the threadId 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:

ParameterTypeDescription
typeStringThe 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:
  • HS_EMAIL_ADDRESS: identifier value must have a valid email address.
  • HS_PHONE_NUMBER: identifier value must be a valid phone number, based on the logic in libphonenumber.
  • CHANNEL_SPECIFIC_OPAQUE_ID: identifier value does not require any format validation to be performed, except to check it isn't blank. This option is intended for use in channels with their own concept of "addresses" (e.g., usernames, UUIDs, or chat handles).
valueStringThe 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:

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

ParameterTypeDescription
inboxIdStringThe 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.
nameStringThe friendly name that will appear to HubSpot users in their account.
deliveryIdentifierStringA 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).
authorizedBooleanBy 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.

custom-channel-account-connection-apiAny 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.

custom-channel-account-connection-flow-huddle-hub-dialog

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:

ParameterTypeDescription
accountTokenStringA 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.
channelIdNumberThe ID of your custom channel.
inboxIdNumberThe ID of the help desk or inbox that the HubSpot admin wants to connect your channel to.
portalIdNumberThe ID of the HubSpot account attempting to connect their account to your custom channel.
redirectUrlStringThe 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:

ParameterTypeDescription
accountTokenStringAs 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.
channelIdNumberThe ID of your custom channel, provided as a path parameter in the URL of your request.
accountNameStringThis 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.
successfully-connected-huddlehub-account
deliveryIdentifierDeliveryIdentifierProvided 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:

custom-account-channel-connection-flow-api-doc

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:

FieldTypeDescription
textStringThe plaintext content of your message.
richTextStringAn optional string that represents the HTML markup for the formatted text content of the message.
channelAccountIdStringThe ID of the channel account receiving the message.
integrationThreadIdStringA 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.
integrationIdempotencyIdStringAn 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.
inReplyToIdStringAn optional string you can use to reference the message ID of an existing message that this message is a direct reply to.
messageDirectionStringA required string that should be set to "INCOMING".
sendersArrayA 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.
recipientsArrayA 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.
timestampStringAn 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.
attachmentsArrayAn 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:

ParameterTypeDescription
typeStringA required string that must be set to "FILE".
fileIdStringThe HubSpot file ID for the uploaded file that the attachment will reference.
fileUsageTypeStringAn 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:

ParameterTypeDescription
typeStringA required string that must be set to "QUICK_REPLIES".
quickRepliesArrayA list of one or more predefined responses. Each quick reply is an object that should include the following fields:
  • value: a string that provides the text content of the reply, or the URL to visit when the option is clicked.
  • label: an optional string that will appear instead of the raw value when presenting the option to the user.
  • valueType: whether to treat the option as a hyperlink (with the value as the URL and the label as text) or as plaintext (in which case the label is used as the option text).

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:

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:

ParameterTypeDescription
typeStringA string that specifies the webhook event type, which will be "OUTGOING_CHANNEL_MESSAGE_CREATED".
portalIdStringThe ID of the HubSpot account from which the message was sent.
channelIdStringThe ID of the custom channel.
eventTimestampStringWhen the event occurred, represented as an ISO8601 timestamp.
messageStringAn object that provides details about the outgoing message. Each of the fields of this message are detailed in the message table below.
eventIdStringUnique reference to a specific message over a given channel used for debugging.
channelIntegrationThreadIdsArrayThe 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:

FieldTypeDescription
idStringA unique message ID
typeStringA string that's hard-coded to "MESSAGE".
channelIdStringThe ID of your custom channel.
channelAccountIdStringThe ID of the channel account receiving the message.
conversationsThreadIdStringThe ID of the thread in the conversations inbox that includes this message.
createdAtStringAn ISO8601 timestamp representing the time when the user hit Send from within the HubSpot message composer.
createdByStringA string representing the actorId of the HubSpot user who sent the message.
sendersArrayA 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.
recipientsArrayA 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.
textStringThe plaintext content of your message.
richTextStringAn optional string that represents the HTML markup for the formatted text content of the message.
directionchannelAccountId"OUTGOING"
inReplyToIdStringAn optional string you can use to reference the message ID of an existing message that this message is a direct reply to.
truncationStatusString"NOT_TRUNCATED"
statusString"SENT"
attachmentsArrayAn 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.
ParameterTypeDescription
typeStringA string that specifies the webhook event type.
portalIdStringThe HubSpot portal ID associated with the custom channel.
channelIdStringThe channel ID of your custom channel.
eventTimestampStringWhen the event occurred, represented as an ISO8601 timestamp.
channelAccountIdStringThe ID of the custom channel account.
channelAccountDeliveryIdentifierStringThe 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.