Use this operation to test agent behavior or execute tools with controlled inputs. For production conversation integrations, use the Agent runtime. Tool execution can affect connected services.
Endpoint
GET
/v1/stable/conversation-state/{userID}

Returns the stored state for one conversation - where it stands and what its variables hold - addressed by the same userID used to run it.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

userID
string
required

The ID identifying this conversation. Any stable string you choose; the same value addresses the same conversation on every call.

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

version
enum<string>
required

Which version of the environment to read: the editable draft or the published one.

Available options: draft, published

Response

200 - application/json

Returns the user's session state for the requested version of the environment: every variable and its current value, the runtime storage carried between turns, and the execution stack showing which diagram and node the conversation is sitting on.

state
object
required
StableConversationState — see its attributes above
Use this operation to test agent behavior or execute tools with controlled inputs. For production conversation integrations, use the Agent runtime. Tool execution can affect connected services.
Endpoint
PATCH
/v1/stable/conversation-state/{userID}

Changes the stored state of a live conversation, which is how a caller seeds or corrects variables between turns without replaying the conversation.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

userID
string
required

The ID identifying this conversation. Any stable string you choose; the same value addresses the same conversation on every call.

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

version
enum<string>
required

Which version of the environment to read: the editable draft or the published one.

Available options: draft, published

Request body

stack
object[]
required

The execution stack for the conversation, from root to innermost frame.

storage
object
required

Internal runtime storage persisted across turns of the session.

variables
object
required

The current values of the agent variables for this session.

Response

200 - application/json

Confirms the conversation state was written for that user. The body carries a message only, so fetch the state again to see the stack, storage, and variables as they now stand.

message
string
required

A human-readable message confirming the update.

Use this operation to test agent behavior or execute tools with controlled inputs. For production conversation integrations, use the Agent runtime. Tool execution can affect connected services.
Endpoint
DELETE
/v1/stable/conversation-state/{userID}

Discards the stored state for one conversation, so the next turn on that userID begins from the start. The response carries only a confirmation message.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

userID
string
required

The ID identifying this conversation. Any stable string you choose; the same value addresses the same conversation on every call.

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

version
enum<string>
required

Which version of the environment to read: the editable draft or the published one.

Available options: draft, published

Response

200 - application/json

Confirms the user's stored state was deleted. The body is a message only, so nothing of the discarded stack, storage, or variables comes back with it.

message
string
required

A human-readable message confirming the deletion.

Use this operation to test agent behavior or execute tools with controlled inputs. For production conversation integrations, use the Agent runtime. Tool execution can affect connected services.
Endpoint
PATCH
/v1/stable/conversation-state/{userID}/variables

Updates variables in the conversation state by merging with the properties in the request body.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

userID
string
required

The ID identifying this conversation. Any stable string you choose; the same value addresses the same conversation on every call.

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

version
enum<string>
required

Which version of the environment to read: the editable draft or the published one.

Available options: draft, published

Request body

variables
object
required

Variable values to set on the conversation session, keyed by variable name.

Response

200 - application/json

Confirms the supplied variables were merged into the session's existing values. The response is a message only, so read the state back if you need the merged result.

message
string
required

A human-readable message confirming the update.

Schemas

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