canonical: https://jentic.com/apis/hubspot.com/hubspot-conversations-inbox-messages

# HubSpot Conversations Inbox & Messages

The HubSpot Conversations Inbox & Messages API exposes the shared inbox model that backs HubSpot Service Hub conversations. It returns inboxes, threads, individual messages, channels, channel accounts, and actor metadata, and allows sending replies, archiving threads, and updating thread state. The API spans the core surface needed to read history and post into existing conversations across email, chat, and connected channels.

## For AI agents

Read HubSpot conversation threads, send messages into existing threads, and manage inbox metadata across email and chat channels. Useful for agents triaging or responding to support conversations.

## Scope

Does not configure custom channels, identify anonymous web visitors, or manage CRM contact records - use for HubSpot inbox thread and message operations only.

## Capabilities

- List conversations inboxes connected to the HubSpot account
- Retrieve a thread, its message history, and original message content
- Send a reply message into an existing thread
- Archive a thread or update its assignee, status, or metadata
- List channels and channel accounts available for conversations
- Look up actors (users or visitors) associated with messages
- Read messages individually or in batches by thread

## Use cases

### AI Triage of Support Threads

Pull recent threads from a HubSpot Service Hub inbox, summarise each, and assign them to the right team member or send a templated first response. The Inbox & Messages API exposes thread listings, full message history, and a send-message endpoint, which is the full read-and-respond loop a triage agent needs.

Example prompt: GET /conversations/v3/conversations/threads, then for each unassigned thread GET its messages and POST /conversations/v3/conversations/threads/{threadId}/messages with a triage reply.

### Conversation Archival and Audit

Export thread history for compliance or analytics by paging through threads and pulling original message content. The API returns each message's raw content via GET /conversations/v3/conversations/threads/{threadId}/messages/{messageId}/original-content, suitable for archival into a data warehouse.

Example prompt: Iterate threads via GET /conversations/v3/conversations/threads, fetch each thread's messages, and store the original-content payload to S3.

### Multi-Channel Reply Bot

Build a reply bot that responds across the channels connected to a HubSpot inbox. The API exposes channels and channel accounts, and POST to a thread's messages endpoint sends a reply on the appropriate channel automatically based on the thread's origin.

Example prompt: On a webhook for a new thread, GET /conversations/v3/conversations/threads/{threadId}, generate a reply, and POST /conversations/v3/conversations/threads/{threadId}/messages.

### Agent-Driven Inbox Operations

Wire a HubSpot inbox into an AI agent through Jentic so the agent can read threads, send replies, and archive resolved conversations. Jentic isolates the HubSpot OAuth token from the agent's reasoning context and exposes each operation by intent rather than by URL.

Example prompt: Use Jentic search 'send a reply into a HubSpot conversation thread', load the schema for POST /conversations/v3/conversations/threads/{threadId}/messages, and execute with the threadId and reply text.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /conversations/v3/conversations/inboxes | List conversations inboxes |
| GET | /conversations/v3/conversations/threads | List threads |
| GET | /conversations/v3/conversations/threads/{threadId} | Get a single thread |
| PATCH | /conversations/v3/conversations/threads/{threadId} | Update a thread |
| GET | /conversations/v3/conversations/threads/{threadId}/messages | Get message history for a thread |
| POST | /conversations/v3/conversations/threads/{threadId}/messages | Send a message to a thread |
| DELETE | /conversations/v3/conversations/threads/{threadId} | Archive a thread |

## Key resources

- **Inboxes** — Top-level conversations inboxes that group threads.
- **Threads** — Conversation threads holding ordered messages.
- **Messages** — Individual messages including original-content retrieval.
- **Channels** — Connected channels (email, chat) and channel accounts.
- **Actors** — Senders and recipients on messages.

## Why Jentic

- **Setup:** Wiring HubSpot Conversations by hand means learning its OAuth2 access token or private app token auth with the conversations scopes, targeting the api.hubapi.com host, and paging inbox threads and messages yourself. Through Jentic you install once, import HubSpot Conversations from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Conversations API puts the thread id in the URL path (/conversations/v3/conversations/threads/{threadId}), so a rule can pin your agent to one thread for reading, updating, and posting messages. You choose the operations it may call, so deleting a thread 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 'send a HubSpot message' or 'list HubSpot inbox threads', and Jentic returns the matching Conversations operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot Conversations Custom Channels** — Register and manage custom channels feeding into HubSpot inboxes.
- **HubSpot Visitor Identification** — Identify authenticated visitors before they post into a thread.
- **HubSpot CRM Contacts** — Resolve a thread's actor to a CRM contact record.

## FAQ

### What authentication does the HubSpot Conversations Inbox & Messages API use?

OAuth 2.0 authorization code flow or a private app token in the `private-app-legacy` header. Jentic stores the credential encrypted and exposes only a scoped execution token to the agent.

### Can I send a reply into an existing thread with this API?

Yes. POST /conversations/v3/conversations/threads/{threadId}/messages sends a message into the thread, routed automatically through the channel the thread originated on.

### What are the rate limits for the Conversations API?

Standard HubSpot API limits apply - roughly 100 requests per 10 seconds per OAuth app and daily caps on paid tiers. For high-volume inbox polling, prefer webhooks and pull thread detail only when an event arrives.

### How do I summarise a thread through Jentic?

Search Jentic for `get HubSpot thread messages`, load the schema for GET /conversations/v3/conversations/threads/{threadId}/messages, execute, and feed the message bodies into your LLM. Install with `pip install jentic` and authenticate using `JENTIC_AGENT_API_KEY`.

### Does the API expose the original content of an email message in a thread?

Yes. GET /conversations/v3/conversations/threads/{threadId}/messages/{messageId}/original-content returns the raw original message content, useful for archival or for showing full email source to a reviewer.

### Can I limit what my agent is allowed to do with the HubSpot Conversations Inbox & Messages API?

Yes. Because you run Jentic One yourself, your own rules decide which Conversations operations the agent may call and which HubSpot credential it uses, so you can allow reading threads and posting a reply while excluding archiving a thread via DELETE /conversations/v3/conversations/threads/{threadId}. Since the thread id sits in the URL path, a rule can also pin the agent to a single thread for getting messages, updating the thread, and sending a reply. The HubSpot token stays with your instance and is added only at execution time, never reaching the agent's prompt or context.