Conversations API

Interact with your AI agent, manage session state, and control user variables. Every endpoint requires a valid API key passed as Authorization: Bearer cdt_xxx.

Endpoints

POST

/api/v1/conversations/:userId/interact

Send a message and get a response (non-streaming)

POST

/api/v1/conversations/:userId/interact/stream

Send a message and receive response as SSE stream

GET

/api/v1/conversations/:userId/state

Get the current session state for a user

PUT

/api/v1/conversations/:userId/state

Replace the entire session state

PATCH

/api/v1/conversations/:userId/variables

Merge variables into the current state

DELETE

/api/v1/conversations/:userId/state

Delete the session state (reset conversation)

Interact

Send a user action (text message, button click, media) and receive the agent's response traces.

Request

POST /api/v1/conversations/user_123/interact
Authorization: Bearer cdt_abc123...
Content-Type: application/json

{
  "action": {
    "type": "text",
    "payload": "I need help with my account"
  },
  "versionId": "development"
}

Response

[
  {
    "type": "text",
    "payload": {
      "message": "Of course! I'd be happy to help with your account. What specific issue are you experiencing?"
    }
  }
]

Action Types

Type	Payload	Description
text	string	Text message from user
launch	null	Start or resume conversation
button	{ label, value }	Button click
media	{ url, mimeType }	Media attachment

Stream

Same as interact, but returns traces as Server-Sent Events for real-time streaming. The stream ends with a [DONE] event.

Request

POST /api/v1/conversations/user_123/interact/stream
Authorization: Bearer cdt_abc123...
Content-Type: application/json

{
  "action": { "type": "text", "payload": "Hello" }
}

SSE Response — agentic mode (with tool call)

data: {"type":"completion-start","payload":{"text":""}}

data: {"type":"debug","payload":{"level":"debug","message":"harness round 1 started"}}

data: {"type":"tool-call","payload":{"phase":"start","toolName":"kb_search","callId":"c1"}}

data: {"type":"tool_call","payload":{"name":"kb_search","argsJson":"{\"query\":\"refunds\"}","resultJson":"{...}","durationMs":420}}

data: {"type":"tool-call","payload":{"phase":"end","toolName":"kb_search","callId":"c1"}}

data: {"type":"text","payload":{"message":"Sure — refunds are processed within 3 business days."}}

data: {"type":"choice","payload":{"buttons":[...]}}

data: {"type":"completion-end","payload":{"text":"Sure — refunds are processed within 3 business days."}}

data: {"type":"state","payload":{"variables":{...}}}

data: [DONE]

SSE event types

The stream is a sequence of typed events. The widget renders user-visible types and ignores the rest. Other consumers (operator dashboards, simulators, audit logs) can use the full set.

Type	When	User-visible?
completion-start	Turn begins. Empty payload.	No (envelope).
completion-continue	Token-level streaming delta (workflow agent step only).	Yes — appended to the bubble.
text	A complete agent text bubble.	Yes.
choice	Buttons emitted (phase enter or show_buttons).	Yes.
cardV2 / carousel / media	Rich cards / images / files.	Yes.
badge / tip / summary / action-steps / contact-card	UI builtin tools (agentic mode).	Yes (when enabled).
tool-call	Lifecycle: { phase: 'start' \| 'end' }. Fires before / after each tool dispatch.	As a spinner / typing indicator.
tool_call	Post-dispatch detail with full args + result + duration.	No — for the simulator timeline.
state_diff	set_state / handoff merged keys (added / changed / removed).	No — for the simulator.
handoff	Playbook invoked (success or guard error).	No — operator.
debug	Diagnostic events (round started, step entered, etc.).	No — operator.
end	Conversation ended (workflow End step).	No.
completion-end	Turn complete. Payload contains the full assembled text.	No (envelope).
state	Final state snapshot for the turn.	No.

Note the dash-vs-underscore distinction: tool-call (lifecycle, no payload leak) is a different event from tool_call (full detail). Renderers that only need a typing indicator should subscribe to tool-call only.

State Management

Read, replace, patch, or delete the session state for a user. Session state includes variables, conversation history, and internal agent state.

Get state

GET /api/v1/conversations/user_123/state
Authorization: Bearer cdt_abc123...

Patch variables

PATCH /api/v1/conversations/user_123/variables
Authorization: Bearer cdt_abc123...
Content-Type: application/json

{
  "customer_name": "Jane Smith",
  "plan_tier": "premium"
}

Delete state (reset)

DELETE /api/v1/conversations/user_123/state
Authorization: Bearer cdt_abc123...

Parameters

Parameter	Type	Required	Description
userId	string	Yes (path)	Unique identifier for the end user
action	Action	Yes (body)	User action object with type and payload
versionId	string	No (body)	Target version — defaults to "development"