Skip to main content
The current platform has three conversation entry points. Read the public manifest or Chat Widget policy before starting a conversation.

Public Agent conversations

Use /v1/public/agents/{agent_id}/conversations for a published Agent. The configured Agent runtime can answer with a tested model connection, approved Knowledge, ordered rules, and enabled handoff and automation controls. Send X-ContactButton-Protocol: rest for direct REST attribution. Agent protocol parity documents the shared state.

Native Chat routed to Inbox

Use /v1/public/apps/{app_id}/chat to read an active Chat Widget and its chat_policy. Start a conversation at /conversations beneath that path. Supply message or suggested_reply_id, the contact details required by the policy, and chat_consent when requested. This path routes directly to the workspace Inbox without a model call. Both public Agent and native Chat conversations return a participant_token only on creation. Send it as X-Conversation-Token for subsequent messages, image uploads/downloads, and callback capture. Poll /conversations/{conversation_id}/messages?after={message_id}. Upload JPEG, PNG, GIF, or WebP images up to 5 MiB using multipart file at /attachments, then include up to five attachment_ids in a message. Agent attachment and callback routes also require an assigned Chat App context. A message may contain text, a current suggested reply, or uploaded attachments. A callback at /conversations/{conversation_id}/callback requires a phone number and an open conversation. The Chat Widget must allow callback requests. This captures a pending callback for the owner; it is separate from the Page proposal and email-verification flow.

Page conversation compatibility

The /v1/public/pages/{page_id}/conversations routes use the earlier Page chat contract behind NATIVE_CHAT_ENABLED. Page owners choose allowed modes:
  • human — route directly to a person.
  • agent_assisted — use public knowledge first and offer human escalation.
  • agent_to_agent — allow an external agent to converse with the owner’s agent when explicitly enabled.
The default excludes agent-to-agent chat. Conversations store participant type, opaque agent identity, routing mode, messages, and escalation timestamps. Suggested-reply pills are returned as structured options so both the visual widget and an external agent can choose the same guided path. Creation returns an opaque participant_token once. Send it as X-Conversation-Token when posting later messages or requesting a human; the stored conversation contains only its hash. The authenticated workspace inbox can list a conversation, read its messages, mark a human as joined, reply as the owner, and close it. A human-escalation request respects the workspace’s chat notification preference.
The Page compatibility routes and Inbox-routed native Chat provide durable conversation state without automatically calling a model. Published Agent conversations use the configured Agent runtime. The workspace thread API and the older Page conversation inbox have separate resource paths; see Conversations API.