canonical: https://jentic.com/apis/hubspot.com/hubspot-conversations-custom-channels

# HubSpot Conversations Custom Channels

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.

## For AI 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.

## Scope

Does not read native HubSpot inbox threads, identify website visitors, or send transactional email - use for registering and operating custom messaging channels only.

## Capabilities

- 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

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

Example prompt: 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.

Example prompt: 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.

Example prompt: 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 your Jentic One instance, and the agent invokes channel operations by intent rather than constructing requests by hand.

Example prompt: 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

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

## Key resources

- **Custom channels** — Top-level custom channel records under /conversations/v3/custom-channels/.
- **Channel accounts** — Per-account installations under a custom channel.
- **Messages** — Inbound messages published into HubSpot from the external platform.

## Why Jentic

- **Setup:** Wiring HubSpot Custom Channels by hand means learning its OAuth2 access token or private app token auth, targeting the api.hubapi.com host, and registering channels and channel accounts yourself. Through Jentic you install once, import HubSpot Custom Channels from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Custom Channels API puts the channel id in the URL path (/conversations/v3/custom-channels/{channelId}), so a rule can pin your agent to one channel for updating it and publishing messages. You choose the operations it may call, so deleting a channel is not included unless you add it.
- **Credential handling:** Your HubSpot access token or private app token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a HubSpot custom channel' or 'publish a message into HubSpot', and Jentic returns the matching Custom Channels operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot Conversations Inbox & Messages** — Read and reply within the HubSpot inboxes that custom channels feed into.
- **HubSpot Visitor Identification** — Identify authenticated visitors as the actor on inbound chat messages.
- **HubSpot OAuth** — Manage OAuth tokens for the app that owns the custom channel.

## FAQ

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

### Can I limit what my agent is allowed to do with the HubSpot Custom Channels API?

Yes. Because you run Jentic One yourself, your own rules decide which Custom Channels operations and credentials the agent may use. Since the channel id lives in the URL path (/conversations/v3/custom-channels/{channelId}), you can pin the agent to a single channel and allow only the calls you choose, such as publishing messages or updating a message's state. Destructive operations like archiving a channel with DELETE /conversations/v3/custom-channels/{channelId} are excluded unless you explicitly add them.