Conversations Custom Channels

Name: Conversations Custom Channels API
Brand: Conversations Custom Channels
Availability: InStock

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

Quickstart

Get started with Conversations Custom Channels in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"publish a message into a HubSpot custom channel"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

Capabilities

What an agent can do with Conversations Custom Channels API.

Create a custom channel that surfaces in HubSpot's shared inbox

Publish inbound messages from the external platform into HubSpot

Update existing custom channel records and their message metadata

GET STARTED

Start building with Conversations Custom Channels API

Explore with Jentic

View OpenAPI Document

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.

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

Why though 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.

Complementary

HubSpot Conversations Inbox & Messages

Read and reply within the HubSpot inboxes that custom channels feed into.

Use Conversations-conversationsInboxMessages when the agent needs to read threads or send replies once a custom channel has delivered a message.

Complementary

HubSpot Visitor Identification

Identify authenticated visitors as the actor on inbound chat messages.

Pick Conversations-visitorIdentification when the agent needs to attach a verified identity to messages before publishing them via the custom channel.

Complementary

HubSpot OAuth

Manage OAuth tokens for the app that owns the custom channel.

Use Auth-oauth when the agent needs to refresh OAuth tokens that authorise the custom channel app.

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.