> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation state

API operations for conversation state. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## Get state

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

### Endpoint

```http
GET /v1/stable/conversation-state/{userID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `userID`

Required · string

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

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `version`

Required · enum<string>

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

```json
{
  "type": "string",
  "enum": [
    "draft",
    "published"
  ],
  "x-enumNames": [
    "DRAFT",
    "PUBLISHED"
  ]
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableConversationStateResponse"
}
```

Example:

```json
{
  "state": {
    "stack": [
      {
        "nodeID": "<string>",
        "diagramID": "<string>",
        "name": "<string>",
        "storage": {},
        "variables": {},
        "commands": [
          {
            "type": "<string>"
          }
        ],
        "dynamicCommands": {}
      }
    ],
    "storage": {},
    "variables": {}
  }
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf conversation state get --user-id <userID> --project-id <projectID> --environment-alias <environmentAlias> --version <version>
```


## Update state

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

### Endpoint

```http
PATCH /v1/stable/conversation-state/{userID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `userID`

Required · string

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

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `version`

Required · enum<string>

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

```json
{
  "type": "string",
  "enum": [
    "draft",
    "published"
  ],
  "x-enumNames": [
    "DRAFT",
    "PUBLISHED"
  ]
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableConversationUpdateStateRequest"
      }
    }
  }
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "stack": [
    {
      "nodeID": "<string>",
      "diagramID": "<string>",
      "name": "<string>",
      "storage": {},
      "variables": {},
      "commands": [
        {
          "type": "<string>"
        }
      ],
      "dynamicCommands": {}
    }
  ],
  "storage": {},
  "variables": {}
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "stack": [
      {
        "nodeID": "<string>",
        "diagramID": "<string>",
        "name": "<string>",
        "storage": {},
        "variables": {},
        "commands": [
          {
            "type": "<string>"
          }
        ],
        "dynamicCommands": {}
      }
    ],
    "storage": {},
    "variables": {}
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "stack": [
        {
          "nodeID": "<string>",
          "diagramID": "<string>",
          "name": "<string>",
          "storage": {},
          "variables": {},
          "commands": [
            {
              "type": "<string>"
            }
          ],
          "dynamicCommands": {}
        }
      ],
      "storage": {},
      "variables": {}
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf conversation state update --user-id <userID> --project-id <projectID> --environment-alias <environmentAlias> --version <version> <<'JSON'
{
  "stack": [
    {
      "nodeID": "<string>",
      "diagramID": "<string>",
      "name": "<string>",
      "storage": {},
      "variables": {},
      "commands": [
        {
          "type": "<string>"
        }
      ],
      "dynamicCommands": {}
    }
  ],
  "storage": {},
  "variables": {}
}
JSON
```


## Delete state

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.

### Endpoint

```http
DELETE /v1/stable/conversation-state/{userID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `userID`

Required · string

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

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `version`

Required · enum<string>

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

```json
{
  "type": "string",
  "enum": [
    "draft",
    "published"
  ],
  "x-enumNames": [
    "DRAFT",
    "PUBLISHED"
  ]
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDeleteResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request DELETE \
  --url 'https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.delete(
    'https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf conversation state delete --user-id <userID> --project-id <projectID> --environment-alias <environmentAlias> --version <version>
```


## Update variables

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

### Endpoint

```http
PATCH /v1/stable/conversation-state/{userID}/variables
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `userID`

Required · string

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

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `version`

Required · enum<string>

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

```json
{
  "type": "string",
  "enum": [
    "draft",
    "published"
  ],
  "x-enumNames": [
    "DRAFT",
    "PUBLISHED"
  ]
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableConversationUpdateVariablesRequest"
      }
    }
  }
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>/variables?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "variables": {}
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>/variables?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "variables": {}
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v1/stable/conversation-state/<userID>/variables?projectID=<projectID>&environmentAlias=<environmentAlias>&version=<version>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "variables": {}
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf conversation state update-variables --user-id <userID> --project-id <projectID> --environment-alias <environmentAlias> --version <version> <<'JSON'
{
  "variables": {}
}
JSON
```


## Schema definitions

### StableConversationState

```json
{
  "type": "object",
  "properties": {
    "stack": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nodeID": {
            "description": "The ID of the node currently being executed in this stack frame.",
            "nullable": true,
            "type": "string"
          },
          "diagramID": {
            "type": "string",
            "description": "The ID of the diagram this stack frame is executing."
          },
          "name": {
            "nullable": true,
            "description": "The name of the diagram this stack frame is executing.",
            "type": "string"
          },
          "storage": {
            "type": "object",
            "additionalProperties": {},
            "description": "Internal runtime storage scoped to this stack frame."
          },
          "variables": {
            "type": "object",
            "additionalProperties": {},
            "description": "Variable values scoped to this stack frame."
          },
          "commands": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "type"
              ],
              "additionalProperties": {}
            }
          },
          "dynamicCommands": {
            "description": "Commands registered dynamically at runtime, keyed by command name.",
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "type"
              ],
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "diagramID",
          "name",
          "storage",
          "variables"
        ]
      },
      "description": "The execution stack for the conversation, from root to innermost frame."
    },
    "storage": {
      "type": "object",
      "additionalProperties": {},
      "description": "Internal runtime storage persisted across turns of the session."
    },
    "variables": {
      "type": "object",
      "additionalProperties": {},
      "description": "The current values of the agent variables for this session."
    }
  },
  "required": [
    "stack",
    "storage",
    "variables"
  ]
}
```

### StableConversationStateResponse

```json
{
  "type": "object",
  "properties": {
    "state": {
      "$ref": "#/components/schemas/StableConversationState"
    }
  },
  "required": [
    "state"
  ]
}
```

### StableConversationUpdateStateRequest

```json
{
  "type": "object",
  "properties": {
    "stack": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nodeID": {
            "description": "The ID of the node currently being executed in this stack frame.",
            "nullable": true,
            "type": "string"
          },
          "diagramID": {
            "type": "string",
            "description": "The ID of the diagram this stack frame is executing."
          },
          "name": {
            "nullable": true,
            "description": "The name of the diagram this stack frame is executing.",
            "type": "string"
          },
          "storage": {
            "type": "object",
            "additionalProperties": {},
            "description": "Internal runtime storage scoped to this stack frame."
          },
          "variables": {
            "type": "object",
            "additionalProperties": {},
            "description": "Variable values scoped to this stack frame."
          },
          "commands": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "type"
              ],
              "additionalProperties": {}
            }
          },
          "dynamicCommands": {
            "description": "Commands registered dynamically at runtime, keyed by command name.",
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "type"
              ],
              "additionalProperties": {}
            }
          }
        },
        "required": [
          "diagramID",
          "name",
          "storage",
          "variables"
        ]
      },
      "description": "The execution stack for the conversation, from root to innermost frame."
    },
    "storage": {
      "type": "object",
      "additionalProperties": {},
      "description": "Internal runtime storage persisted across turns of the session."
    },
    "variables": {
      "type": "object",
      "additionalProperties": {},
      "description": "The current values of the agent variables for this session."
    }
  },
  "required": [
    "stack",
    "storage",
    "variables"
  ],
  "additionalProperties": false
}
```

### StableConversationUpdateVariablesRequest

```json
{
  "type": "object",
  "properties": {
    "variables": {
      "type": "object",
      "additionalProperties": {},
      "description": "Variable values to set on the conversation session, keyed by variable name."
    }
  },
  "required": [
    "variables"
  ],
  "additionalProperties": false
}
```

### StableDeleteResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the deletion."
    }
  },
  "required": [
    "message"
  ]
}
```

### StableUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    }
  },
  "required": [
    "message"
  ]
}
```
