topic Re: Custom Channels API Is Now Live in Developer Announcements

Custom Channels API Is Now Live

hseligson — Thu, 10 Apr 2025 15:08:44 GMT

We are excited to announce important updates to the Custom Channels API to enhance flexibility, functionality, and integration capabilities now that it's live. The updates prioritize improvements in webhook functionality, message threading, channel metadata display, and validation of delivery identifiers. Additionally, this API is now accessible to a broader range of customers, specifically those with Sales or Service Hub Professional or higher subscriptions. By integrating HubSpot with multiple channels like SMS, Instagram, Telegram, LINE, WhatsApp, and Slack, you can enhance your communication capabilities. Check out the Marketplace Apps for inspiration on how this API can optimize and elevate your messaging strategy.

These changes enhance the API's functionality and improve administrators' experience. Please see below for more details about these important updates.

New Feature: Webhooks for custom channel

We're adding a new webhook type for custom channels. You'll now get a webhook when an admin successfully connects an instance of your custom channel to their Inbox or Help Desk. This webhook will include the details of the newly connected channel instance.

Similar to the CHANNEL_ACCOUNT_UPDATED webhook event, HubSpot will POST a new event to the custom channel's webhookUrl, with the new webhook type of CHANNEL_ACCOUNT_CREATED. The event payload is the same as for the channel account updated event.

See the custom channels webhook documentation for more details.

New Feature: HubSpot-Managed Message Threading

Developers integrating messaging services with the Custom Channels API now have the option to enable HubSpot-managed message threading. This feature provides an alternative to the existing model, where developers generate their own integrationThreadIds. This threading approach is the same as WhatsApp and SMS integrations.

What’s changing?

The channels schema capabilities array now includes a threadingModel option with two possible values:

INTEGRATION_THREAD_ID: this setting requires integrators to include an integrationThreadId in every POST message request. This ID will be returned in the channelIntegrationThreadId property of the OUTGOING_CHANNEL_MESSAGE_CREATED webhook event.
DELIVERY_IDENTIFIER: when this option is selected, integrators should include an integrationThreadId, as HubSpot will automatically generate and manage threadId’s based on the following rules:
- Each set of delivery identifiers (email addresses, phone numbers, etc.) can only have one active thread open at a time.
- Archived threads with the same participants are disregarded.
- Outgoing messages are only published on open threads.
- Incoming messages are tied to the same threadId if the thread is open or has been closed for less than 24 hours—in this case, the thread and any associated ticket will reopen.
- The generated threadId by HubSpot will be included in the channelIntegrationThreadId’s property of the OUTGOING_CHANNEL_MESSAGE_CREATED webhook event.

Developers can now choose the threading model that best suits their use case, enhancing HubSpot's integration flexibility and conversation management efficiency.

New Feature: Channel Metadata Customization

Admins using the Help Desk settings to connect channels from connected apps can now view detailed metadata, including channel name and logo. This enhancement allows developers to configure metadata about their channels through the Custom Channels API, boosting admin confidence and clarity when setting up channel integrations.

What’s changing?

Two new string properties have been added to the Channel schema:

channelLogoUrl: this property allows developers to specify a URL for the channel’s logo, enhancing visual identification.
channelDescription: this property enables developers to provide a short description of the channel, offering context and details about its purpose and functionality.

These properties are accessible via the Channels endpoints and can be read, written, and updated, offering flexibility in how developers present their channel integrations.

New Feature: deliveryIdentifier Validation on Channel and Channel Account Creation

The Custom Channels API now enforces validation for the property deliveryIdentifierTypes when creating new channels, and a deliveryIdentifier when creating channel accounts. These fields must now contain a valid value to ensure the channel integration functions correctly.

Previously, these fields were optional and could be set as null, which led to situations where the API request returned success, but the channel functionality did not work. This change does not impact existing users’ ability to send or receive messages as the API relies on a channel account identified for directing messages.

What’s changing?

No changes are required for existing users. HubSpot has backfilled existing configurations based on the channel accounts and previously published messages.
For new users, developers must specify a deliveryIdentiferTypes and deliveryIdentifier value when integrating channels with this new validation.

Please refer to the updated API documentation for additional details.

Questions or comments? Please join the forum below for a peer-to-peer discussion.

Re: Custom Channels API Is Now Live

reina96 — Mon, 02 Jun 2025 08:45:44 GMT

Hi. We have connected Zalo OA chat (a local chat in Vietnam) using the Custom channel API, and it works quite well on the website. But on mobile, we can only view messages and comments, but cannot reply directly like on the web. Is this related to the API, or are we missing any settings?

Re: Custom Channels API Is Now Live

hseligson — Wed, 11 Jun 2025 18:34:59 GMT

Hi @reina96 - thank you so much for your comment and for raising this issue!

Custom channel messages can be viewed in the mobile inbox, but replying via mobile isn't currently supported. This isn’t an issue with your setup or the API—it's a limitation of the current mobile inbox feature.

At this time, there are no planned updates for the mobile inbox, which includes limitations around replying to custom channel messages and sending messages from CRM records via mobile. However, this is on our radar, and we'll be sure to share any updates if this changes in the future!

Please ensure you subscribe to the Developer Changelog to stay up to date with these changes and announcements! Thank you!
https://developers.hubspot.com/changelog

Re: Custom Channels API Is Now Live

SFERRER3 — Wed, 18 Jun 2025 22:20:15 GMT

We’re currently exploring the use of this functionality for a public app, and we have three basic but important questions:
API Request Limits
We understand that the limit for public applications is 110 requests per 10 seconds. However, during a conversation flow, this can be quite limiting. Does this same limit apply to the Custom Channel API?
File Limits
Our application involves frequent file sharing. What are the file size or type limits that apply in this context?
Required Plan for Custom Channels
There’s some confusion regarding the plan requirements for using a custom channel. Some documentation indicates that any Pro Suite is enough, while other sources suggest it requires a Service Enterprise plan. Could you please clarify this?
Thank you in advance for your help!

Re: Custom Channels API Is Now Live

JVanRysselber — Thu, 27 Nov 2025 11:34:39 GMT

I got the same opinion here. When testing the channels, the issue we came across was that the documentation is insufficient. It tells us to have plan x but when trying to deploy we get portal errors saying we don't have the right plan activated. It's also really weird to put the custom channels behind a certian paywall, when it doesn't serve any extra purpose besides logging messages.

Re: Custom Channels API Is Now Live

BérangèreL — Thu, 27 Nov 2025 11:47:50 GMT

Hi @JVanRysselber and a very warm welcome! We’re so glad to have you here in the HubSpot Community.

Thank you for sharing your experience with the Custom Channels API, it’s always helpful for us to hear from you.

To ensure your feedback reaches our product team, could you please submit it through the HubSpot Developer Feedback form?

And if you have any extra details or suggestions, please feel free to include them there as well!

For reference, here are the ressources:

- Custom channels
- API usage guidelines and limits

Thank you again, and wishing you a fantastic day!
Bérangère

Re: Custom Channels API Is Now Live

JVanRysselber — Thu, 27 Nov 2025 13:49:56 GMT

The documentation you linked doesn't tell us anything about the required subscriptions.

"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."

This is what you mention in your documentation. But these tell us nothing about what hubs are needed on what tier.

This is what is referenced on the deeper pages. Can you explain why we have to have a certain hub/subscription to install apps with the use of custom channels?

Re: Custom Channels API Is Now Live

BérangèreL — Mon, 01 Dec 2025 15:44:10 GMT

Hi @JVanRysselber and thanks for sharing your valuable feedback, I have passed it along internally.

I can see that custom channels require Sales Hub Professional or Service Hub Professional or higher to use.

The subscription tier requirements determine whether users can install and use apps with custom channels in their HubSpot account, it's not about building the app, but about who can use it.

I hope this helps!
Bérangère