HubSpot Conversations Custom Channels
Browse all Hubspot APIs✓ Official Vendor SpecCommunicationsChat Messagingoauth2, apiKey13 EndpointsREST
For Agents
Register and operate custom messaging channels inside HubSpot conversations, including publishing messages and managing channel accounts. Useful for agents bridging an external chat platform into HubSpot.
Use for: Create a custom conversation channel for an external chat platform, Publish an inbound message from an external messenger into HubSpot, Register a channel account when a user installs the integration, Update the state of a previously published custom-channel message
Not supported: Does not read native HubSpot inbox threads, identify website visitors, or send transactional email — use for registering and operating custom messaging channels only.
The HubSpot Conversations Custom Channels API lets developers register external messaging surfaces — such as a proprietary chat platform or third-party messenger — as channels inside HubSpot's shared inbox. It supports creating and updating channels and channel accounts, publishing inbound messages, updating message state, and managing channel account staging tokens used for installation flows. With this API a custom channel can behave like native HubSpot conversations channels.
Install Jentic One Beta
Connect the Conversations Custom Channels to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Conversations Custom Channels, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Conversations Custom Channels API.
Create a custom channel that surfaces in HubSpot's shared inbox
Register channel accounts representing connected end users or threads
Publish inbound messages from the external platform into HubSpot
Update existing custom channel records and their message metadata
Manage channel account staging tokens used during install handshakes
Archive a custom channel when the integration is removed
Query channel accounts attached to a specific custom channel
Use Cases
Patterns agents use Conversations Custom Channels API for, with concrete tasks.
★ Bridging an External Chat into HubSpot
A SaaS vendor with its own chat product surfaces conversations inside HubSpot Service Hub by registering a custom channel and publishing each new external message into HubSpot. POST /conversations/v3/custom-channels/ creates the channel; POST /conversations/v3/custom-channels/{channelId}/messages publishes inbound messages so they appear in the shared inbox.
POST /conversations/v3/custom-channels/ once at install time to create the channel, then POST /conversations/v3/custom-channels/{channelId}/messages for each new inbound message.
Per-Account Channel Provisioning
Provision a separate channel account whenever a HubSpot customer connects their workspace in the external platform. The API supports creating, updating, and querying channel accounts, plus rotating staging tokens used during the OAuth-style install handshake.
On install completion, POST /conversations/v3/custom-channels/{channelId}/channel-accounts with the connected workspace identifiers.
Sync Read and Delivered State
Mirror external read or delivered receipts back into HubSpot so the inbox view stays in sync with the source platform. PATCH /conversations/v3/custom-channels/{channelId}/messages/{messageId} updates a published message's state without re-publishing the body.
On a read-receipt event, PATCH /conversations/v3/custom-channels/{channelId}/messages/{messageId} setting the new status.
Agent-Driven External Bridge
Use Jentic to let an integration agent register channels and publish messages on behalf of customers without bespoke HubSpot client code. The HubSpot OAuth token is held in the Jentic vault, and the agent invokes channel operations by intent rather than constructing requests by hand.
Use Jentic search 'publish a message into a HubSpot custom channel', load the POST /conversations/v3/custom-channels/{channelId}/messages schema, and execute with the channelId and message payload.
Key Endpoints
13 endpoints — the hubspot conversations custom channels api lets developers register external messaging surfaces — such as a proprietary chat platform or third-party messenger — as channels inside hubspot's shared inbox.
METHOD
PATH
DESCRIPTION
GET
/conversations/v3/custom-channels/
List all custom channels for the app
POST
/conversations/v3/custom-channels/
Create a custom channel
PATCH
/conversations/v3/custom-channels/{channelId}
Update a custom channel
POST
/conversations/v3/custom-channels/{channelId}/messages
Publish a message
PATCH
/conversations/v3/custom-channels/{channelId}/messages/{messageId}
Update a published message
POST
/conversations/v3/custom-channels/{channelId}/channel-accounts
Create a channel account
DELETE
/conversations/v3/custom-channels/{channelId}
Archive a custom channel
GET
/conversations/v3/custom-channels/
List all custom channels for the app
POST
/conversations/v3/custom-channels/
Create a custom channel
PATCH
/conversations/v3/custom-channels/{channelId}
Update a custom channel
POST
/conversations/v3/custom-channels/{channelId}/messages
Publish a message
PATCH
/conversations/v3/custom-channels/{channelId}/messages/{messageId}
Update a published message
POST
/conversations/v3/custom-channels/{channelId}/channel-accounts
Create a channel account
DELETE
/conversations/v3/custom-channels/{channelId}
Archive a custom channel
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot OAuth and private app tokens for Custom Channels are stored encrypted in the Jentic vault. The raw credential never enters the agent's reasoning context — only a scoped execution token does.
Intent-based discovery
Agents search Jentic with intents like 'create a HubSpot custom channel' or 'publish a message into HubSpot' and Jentic returns the matching Custom Channels operation with its input schema, ready to call.
Time to first call
Direct integration including OAuth, channel registration, and message publish flow typically takes 3-5 days. Through Jentic: a few hours.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Conversations Custom Channels API through Jentic.
What authentication does the HubSpot Custom Channels API use?
OAuth 2.0 authorization code flow, a private app token in the `private-app` header, or developer hapikey as a query parameter. Through Jentic, credentials are stored encrypted in the vault and the agent only sees a scoped execution token.
Can I publish a message from an external platform into HubSpot's inbox?
Yes. POST /conversations/v3/custom-channels/{channelId}/messages publishes a message into the channel so it appears in the shared inbox alongside native conversation channels.
What are the rate limits for the Custom Channels API?
Standard HubSpot API limits apply — roughly 100 requests per 10 seconds per OAuth app and daily caps on paid tiers. Spread message publication evenly to stay below the per-second ceiling.
How do I register a custom channel through Jentic?
Search Jentic for `create a HubSpot custom channel`, load the POST /conversations/v3/custom-channels/ schema, and execute with the channel name and webhook configuration. Install with `pip install jentic` and authenticate using `JENTIC_AGENT_API_KEY`.
Can I update the state of a previously published message?
Yes. PATCH /conversations/v3/custom-channels/{channelId}/messages/{messageId} updates an already-published message — useful for syncing read receipts or delivery status from the source platform.
GET STARTED