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 community forum for a peer-to-peer discussion.