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