Variables & Secrets
Variables store dynamic data during conversations. Secrets hold sensitive credentials securely. Together, they let your workflows personalize responses, pass data between steps, and connect to external services safely.
Variables
Variables are named data containers that persist throughout a conversation session. They can store user input, API responses, computed values, or any other data your workflow needs to remember from one step to the next. Each variable has a name like customer_name or order_id and an optional default value.
Defining Variables
Define variables in the Variables tab of your project. Each variable needs a unique name and an optional default value. Variables are available to all workflows within the project.
Setting Variable Values
Variables can be set in several ways during a conversation:
| Method | Step Type | Description |
|---|---|---|
| Listen step | listen | Stores user input in a specified variable |
| Set step | set | Assigns static values or expressions to variables |
| API response mapping | api | Maps JSON response paths to variables |
| Code output | code | Returns computed values to output variables |
| API (external) | PATCH | Set via PATCH /api/v1/conversations/:userId/variables |
Using Variables
Reference variables in step configurations using their name. Common uses include:
- Condition steps — Branch logic based on variable values (e.g., if
plan_tieris “premium”) - Message templates — Insert variable values into scripted messages
- API requests — Use variables in URL paths, headers, query parameters, and request bodies
- Agent prompts — Reference variables in system prompts for personalized agent behavior
- Playbook inputs — Pass variables as input when invoking a playbook
Secrets
Secrets are encrypted key-value pairs for sensitive data like API tokens, database credentials, or third-party service keys. They differ from variables in important ways:
| Feature | Variables | Secrets |
|---|---|---|
| Storage | Plain text in session | Encrypted at rest |
| Visibility | Visible in dashboard & API | Write-only after creation |
| Scope | Per-session (dynamic) | Per-project (static) |
| Use Case | User data, conversation state | API keys, tokens, passwords |
| In responses | Can appear in messages | Never exposed to users |
Using Secrets
Secrets are available to API steps and tool configurations. Reference them in HTTP headers (e.g., Authorization: Bearer {secret.api_token}) or in tool credential fields. The runtime resolves secret references at execution time without exposing the actual values in logs or responses.
Managing Variables & Secrets
Navigate to the Variables tab in your project to manage both. The interface provides a table view where you can add, edit, and delete variables, and a separate section for secrets. Default values for variables are applied when a new session is created. You can also set variables programmatically via the Conversations API.