curl --request POST \ --url https://realtime-api.voiceflow.com/v1/stable/conversation/script \ --header 'Authorization: Bearer <token>' --header 'Content-Type: application/json' \ --data '{ "messages": [ "<string>" ], "variables": {}, "version": "draft" }'

{ "userID": "<string>", "needsRecompile": true, "turns": [ { "user": "<string>", "agent": [ "<string>" ], "toolCalls": [ "<StableConversationScriptToolCall>" ], "variableChanges": [ "<StableConversationScriptVariableChange>" ], "errors": [ "<string>" ], "ended": true } ], "notSent": [ "<string>" ] }

Authorizations

Authorization

string

header

required

Voiceflow bearer token

Query Parameters

projectID

string

required

The ID of the project to operate on.

environmentAlias

string

required

The alias of the environment to operate on (e.g. main).

Body

messages

string[]

required

The user messages to send, in order, after the launch that starts the conversation.

variables

object

Variable values to set before the launch, keyed by variable name, to start as a known caller.

version

enum<string>

default:"draft"

Whether to talk to the draft or the published version of the environment. Draft unless you pass it.

Available options: draft, published

Response

200 - application/json

Returns one digest per turn: the agent's replies, the tools it called, the variables that changed, and any errors. Messages that were not sent because the script stopped early come back in notSent, and needsRecompile says whether the turns ran against an outdated compile.

userID

string

required

The conversation user ID the script ran as, for reading its state afterwards.

needsRecompile

boolean

required

When true, the script ran against a stale prototype. Compile the environment and run it again; do not treat these turns as proof the latest edits work.

turns

object[]

required

The launch turn first, then one turn per message sent.

Show child attributes

user

string

required

The message sent in this turn. Null for the launch turn that starts the conversation.

agent

string[]

required

The agent's replies in this turn, in order, at most 10, each cut to 1,000 characters. Buttons, cards and carousels come summarised, such as "[buttons: Yes | No]" or "[card: <title>]".

toolCalls

object[]

required

The tools the agent called and the tools its workflow steps ran in this turn, at most 20.

Show child attributes

name

string

required

The tool that ran: by the name the agent called it, or its own name when a workflow step ran it.

arguments

string

required

The arguments the agent passed, as JSON, cut to 300 characters. {} when a workflow step ran the tool.

variableChanges

object[]

required

The variables this turn set, changed or cleared, at most 30. Leaves out the variables that change every turn (vf_now, vf_time, timestamp, vf_memory, last_utterance, last_response, last_event, intent_confidence). The launch turn lists the preset variables and the variables the launch set, not the system variables or the starting values.

Show child attributes

name

string

required

before

string

required

The value before the turn, as JSON cut to 200 characters. Null when it was not set; a null value is the string "null".

after

string

required

The value after the turn, as JSON cut to 200 characters. Null when it is not set; a null value is the string "null".

errors

string[]

required

Errors, failed tool calls, HTTP failures and credit limits the runtime reported in this turn, at most 10, each cut to 300 characters.

ended

boolean

required

True when the agent ended the conversation in this turn.

notSent

string[]

required

Messages that were not sent because the agent ended the conversation, a turn failed or reported errors, or the caller stopped the script first.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Run script

Authorizations

Query Parameters

Body

Response

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks