Skip to main content
The Conversations API exposes the same durable thread and message records used by Taskbox. It is designed for CRMs, support tools, automations, and AI agents that need one customer timeline without taking a dependency on a specific channel provider. Public Agent conversations also expose capability discovery and action requests beneath /v1/public/agents/{agent_id}/conversations/{conversation_id}. These endpoints require the opaque X-Conversation-Token. Assistant messages retain their existing apps cards and add an actions collection containing review, verification, processing, and result state. Sensitive action input remains in the encrypted action record rather than being duplicated into message payloads. Use a bearer token with engagements:read to read threads and messages. Add engagements:manage to send messages or change inbox state.

Resource model

  • A Contact is the customer identity owned by one workspace.
  • A Thread is the Contact-centric timeline shown in Taskbox. One thread can contain several channel conversations.
  • A Conversation is the channel-specific binding within a thread, such as one web-chat session or email thread.
  • A Message belongs to a Conversation and carries channel, direction, content, attachments, delivery state, and timestamps.
This deliberately borrows durable conversations, messages, media, delivery status, pagination, and idempotent mutations from mature messaging APIs. It does not copy carrier-specific participant orchestration, proxy addresses, or paid provider infrastructure that Contact Button does not need.

List threads

Filter by view, channel, or search. Follow meta.next_cursor to page without skipping records while new messages arrive.

Read messages

Read the recent timeline with the thread:
Or page messages independently:

Send a message

Choose one of the thread’s returned Conversations and use its id and channel. Sending is asynchronous; inspect delivery_status and retry only failed outbound messages.
Channel capabilities in the thread response tell clients whether free-form replies, templates, and attachments are currently allowed. These constraints remain enforced server-side.

Follow-ups and bookings

Read GET /v1/workspaces/{workspace_id}/inbox-actions for the workspace timezone, enabled actions, and booking types. For a booking, query /inbox-booking-types/{type_id}/availability with from, to, and timezone first. Create actions beneath /inbox-threads/{thread_id}:
  • POST /follow-ups takes title, a future due_at, timezone, recurrence, and optional message_id. Requires engagements:manage and Contact reminders enabled.
  • POST /bookings takes event_type_id, a future starts_at, timezone, email, and optional name, phone, notes, and message_id. Requires engagements:manage, native booking enabled, and calendar access.
Use a stable Idempotency-Key. An optional source message must belong to the thread. Authenticated bookings act as the workspace operator: they reserve a live slot immediately, create a confirmed booking, and queue calendar synchronization. Public MCP and Page proposals use the separate visitor-review flow.

Attachments and thread state

Upload private attachments at /inbox-attachments, read them at /inbox-attachments/{attachment_id}, and delete authorized attachments with DELETE on that path. Keep downloads behind workspace authorization. Thread updates support open/closed state, starring, unread state, snoozing, hiding, and restoration. Hiding a thread preserves its messages. The Workspace MCP exposes the same Inbox action boundary through seven dedicated tools. MCP writes use request_id and values, rather than a REST header.

Compatibility

Existing /inbox-threads endpoints remain supported and return the same representations. New integrations should use /threads; the alias avoids forcing existing Taskbox and partner integrations to migrate.
This first productized slice is REST and polling friendly. Event webhooks, SDK helpers, participant membership, and delivery callbacks are natural follow-on layers, but are not part of this initial contract.