VX Agents

API directory · Customer Support

HubSpot Conversations Inbox & Threads

v1.0.0 · 15 endpoints · 0 connections · shared by vx.ai

For support and sales reps working out of the HubSpot inbox: find open threads by inbox, contact or ticket, read the full message history, see who the actors are, then reply on the original channel, leave an internal comment or close the thread.

Connect this API to an AI agent Browse all specs

What you can do with HubSpot Conversations Inbox & Threads via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /conversations/v3/conversations/inboxes listInboxes List the conversations inboxes in the account
GET /conversations/v3/conversations/inboxes/{inboxId} getInbox Get one inbox by id
GET /conversations/v3/conversations/channels listChannels List the channel types connected to inboxes (email, chat, Facebook...)
GET /conversations/v3/conversations/channels/{channelId} getChannel Get one channel by id
GET /conversations/v3/conversations/channel-accounts listChannelAccounts List channel accounts (a specific mailbox or chatflow), filtered by channel or inbox
GET /conversations/v3/conversations/channel-accounts/{channelAccountId} getChannelAccount Get one channel account by id
GET /conversations/v3/conversations/threads listThreads List threads filtered by inbox, status, contact, ticket or last message time
GET /conversations/v3/conversations/threads/{threadId} getThread Get one thread with its status, assignee and associated contact
PATCH /conversations/v3/conversations/threads/{threadId} updateThread Close or reopen a thread, or restore an archived one
GET /conversations/v3/conversations/threads/{threadId}/messages listThreadMessages Get the message history of a thread
POST /conversations/v3/conversations/threads/{threadId}/messages sendThreadMessage Reply to the customer on the thread's channel or add an internal comment
GET /conversations/v3/conversations/threads/{threadId}/messages/{messageId} getThreadMessage Get one message in a thread
GET /conversations/v3/conversations/threads/{threadId}/messages/{messageId}/original-content getMessageOriginalContent Get the full original text of a truncated message
GET /conversations/v3/conversations/actors/{actorId} getActor Look up who sent a message (agent, visitor, bot) by actor id
POST /conversations/v3/conversations/actors/batch/read batchReadActors Look up several actors at once

Authentication

private_app_token

Bearer token — sent as Authorization: Bearer <token>

HubSpot private app access token (or an OAuth access token), sent as Authorization: Bearer <token>.

How to get a credential

  1. In HubSpot, open Development (or Settings > Integrations) > Legacy apps / Private apps.
  2. Click Create legacy app > Private, and name it (e.g. VX Agents inbox).
  3. On the Scopes tab add conversations.read and conversations.write.
  4. Create the app and copy the access token (pat-...).

Permissions used

Scope Operations
conversations.read listInboxes, getInbox, listChannels, getChannel, listChannelAccounts, getChannelAccount, listThreads, getThread, listThreadMessages, getThreadMessage, getMessageOriginalContent, getActor, batchReadActors
conversations.write updateThread, sendThreadMessage

Common errors

Status Meaning Fix
401 Token missing, expired or revoked Copy the token again from the private app; rotate it if it was revoked.
403 Scope missing, or the inbox/channel is not available on this HubSpot tier Add the scope listed above to the app and save; check the account has the conversations inbox.
400 Bad body or filter sendThreadMessage needs type (MESSAGE or COMMENT), text, and for messages senderActorId, channelId, channelAccountId and recipients.
429 Rate limit Wait and retry with backoff.

Store the token as a VX Agents credential (Bearer token).

Usage guide

Setup

  • Credential: a HubSpot private app token (pat-...) with conversations.read and conversations.write, stored as a Bearer token.
  • Worth pinning: the inboxId your team works in (from listInboxes), so thread lists stay scoped to one inbox.

Work the inbox

  1. listInboxes to find the inbox id, then listThreads with inboxId and threadStatus=OPEN (add associatedContactId or associatedTicketId to find one customer's threads; sort=latestMessageTimestamp needs latestMessageTimestampAfter too; results are always ascending).
  2. getThread for status, assignee and the associated contact.
  3. listThreadMessages for the history. When a message is marked truncated, call getMessageOriginalContent.
  4. getActor or batchReadActors to turn sender/recipient actor ids (A-123, V-456) into names and emails.
  5. Reply with sendThreadMessage:
    • internal note: {"type": "COMMENT", "text": "...", "attachments": []} (only agents see it);
    • customer reply: type: MESSAGE with text, attachments: [], senderActorId (an agent actor A-<userId>), and channelId, channelAccountId and recipients copied from the latest incoming message in the thread. Add subject for email.
  6. updateThread with {"status": "CLOSED"} when done, or OPEN to reopen. To restore an archived thread, call it with archived=true and body {"archived": false}.

Always show the reply text and the recipient to the user and get a yes before calling sendThreadMessage with type MESSAGE: it is sent to the customer. Confirm before closing threads too.

Good to know

  • Paging: list calls return paging.next.after; pass it as after. limit caps the page size.
  • Timestamps are ISO 8601 UTC (e.g. latestMessageTimestampAfter=2026-10-01T00:00:00Z).
  • listChannels / listChannelAccounts tell you which channel (email, chat, Facebook Messenger, WhatsApp...) and which mailbox or chatflow a thread came in on.
  • Archived threads are hidden unless you pass archived=true.
  • Assigning threads is not included here; assign in HubSpot.
  • Source: HubSpot Conversations API reference (https://developers.hubspot.com/docs/api-reference/legacy/conversations/guide), checked 2026-10-22.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “HubSpot Conversations Inbox & Threads” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs