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.

SSE response example
  • 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 trace event’s data as JSON, then dispatch on the trace’s type.
  • Finish the turn: wait for the SSE end event. 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.

OpenAPI payload schema

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.

OpenAPI payload schema

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.

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.

OpenAPI payload schema

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.

OpenAPI payload schema

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.

OpenAPI payload schema

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.

OpenAPI payload schema

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.

OpenAPI payload schema

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.

OpenAPI payload schema

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.

OpenAPI payload schema

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.

OpenAPI payload schema

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.

JSON response example
  • Display text: read payload.message; use payload.slate for the structured rich-text version. See text traces.
  • Display other output: dispatch on type using the trace index.
  • Check the HTTP status: 402 uses the same envelope for a credit-limit debug trace. See request lifecycle.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.