Event stream
POST /v4/interact/stream returns text/event-stream. Each SSE event named trace carries a trace object in its JSON data. The event named end carries an empty object and finishes the turn’s delivery.
trace event
A JSON trace object carried in the event’s data field.
- Parse complete events: preserve partial text across network reads. A network chunk can split an event or contain multiple events; dispatch after the event’s blank-line terminator.
- Decode the payload: parse a
traceevent’sdataas JSON, then dispatch on the trace’stype. - Finish the turn: wait for the SSE
endevent. If the stream closes first, follow interrupted-stream recovery.
Use an SSE-capable client that supports POST bodies and the Authorization header. Native browser EventSource does not support that request shape. The SSE parsing standard defines event framing; Sending actions owns the HTTP contract.
end event
The event’s JSON data is {}. It finishes delivery of one turn. It does not end the conversation; a trace whose type is end does that.
error event
A runtime failure during streaming produces an SSE event named error, then closes the response. Its data contains serialized error text; it is not a trace payload. Handle it as a failed turn, rather than waiting for a successful end event or replaying the action automatically.
Errors raised before streaming starts return an HTTP error response instead. Check the HTTP status before parsing events; a successful HTTP status alone does not prove the streamed turn completed. See Errors and recovery.
Trace payloads
Dispatch on trace.type. The definitions below cover chat messages and conversation controls. For escalation, use Human agent hand-off.
Messages and UI
text trace
Returned by the Message step, Playbooks, and no-match and no-reply reprompts.
The message field contains the plain text content. The slate field contains the same content in a structured rich-text format. When present, delay gives the pause in milliseconds. Use the supplied value rather than assuming a fixed delay; Voice output does not inherit the project’s chat message delay.
text payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
cardV2 trace
Returned by the Card step. When a card contains buttons, each button’s request.type is a Voiceflow-generated path ID. Pass that value as the action.type in your next request to advance the conversation along the corresponding path.
cardV2 payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
carousel trace
Returned by the Carousel step. The same button handling applies as with cardV2 - pass the button’s request.type as the action.type in your next request.
carousel payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
choice trace
Returned by the Condition step and Playbooks or the Agent when the buttons system tool is enabled. How you handle a choice trace depends on what’s in each button’s request.type.
Path buttons
When buttons are connected to specific paths in your workflow, request.type is a Voiceflow-generated path ID. Pass it directly as action.type in your next request. The label field is optional - if included, its value is set as the last_utterance variable.
To handle this button click, send:
Agent-generated buttons
When the buttons system tool is enabled on Playbook or on the Agent, the agent may dynamically generate buttons. These use request.type: "text" and simulate raw user input rather than triggering a specific path:
choice payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
visual trace
Displays an image, with optional device sizing and layout options.
visual payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
Conversation control
no-reply trace
Returned when a No Reply timeout is active. The timeout value is in seconds.
If the user doesn’t respond within the timeout window, send a no-reply action to retrieve the configured reprompt:
no-reply payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
end trace
Returned when the conversation reaches an End step. On receiving this trace, your application should treat the session as closed.
end payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
goto trace
Instructs the client to re-send the wrapped request on the next turn.
goto payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
entity-filling trace
Requests a value for a named entity, wrapping the intent request being filled.
entity-filling payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
channel-action trace
A channel-specific action, named by the channel integration, with an action-defined payload.
channel-action payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
Non-streaming HTTP alternative
Receive the completed turn as JSON when incremental output is unnecessary.
Read the completed turn
POST /v4/interact returns application/json with a traces array. Each element is a trace, not a separate HTTP response. Process the array in order once the request completes.
- Display text: read
payload.message; usepayload.slatefor the structured rich-text version. See text traces. - Display other output: dispatch on
typeusing the trace index. - Check the HTTP status:
402uses the same envelope for a credit-limit debug trace. See request lifecycle.