Variables
Store reusable configuration values and credentials as Variables, then reference their keys in supported text fields.
What are Variables
Variables supply values at runtime for:
- Assistant instructions
- MCP server URLs and headers
- Any other templated text field that supports dynamic evaluation
How it works
Variables can be stored at Organisation or Project scope. The voice runtime currently loads Project-scoped Variables for the Assistant's Project; it does not automatically fall back to Organisation-scoped Variables. Create the Variables needed by an Assistant in its Project.
Resolution flow
For a Project Variable reference, the runtime looks up the key in the Assistant's Project and replaces the placeholder with its value. It does not load an Organisation Variable as a fallback.
Call-specific sources can override Project Variables. See Data Injection for the full priority order. If no source supplies a value, the placeholder resolves to an empty string.
Variable syntax
Use single or double curly braces with the Variable key to reference a Variable in any supported text field. Both {key} and {{key}} are accepted:
Code
Example in Assistant instructions:
Code
If you have a Variable with key companyName:
Code
It will be replaced at runtime:
Code
Variable entity structure
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | The reference name used in { key } syntax |
value | JSON value | Yes | The value to inject at runtime |
isSecret | boolean | No | When true, the value is treated as sensitive data |
projectId | UUID | No | Links to a Project for Project-scoped Variables |
Creating Variables
The request paths below are relative to the Data API server URL in the API reference, which includes /data_next. See Authentication for API key scopes.
Organisation-level Variable
Use an organization-scoped API key and omit projectId to create an Organisation Variable. For use in a voice Assistant, create a Project-scoped Variable instead:
Code
Project-level Variable
Create a Variable scoped to the Assistant's Project:
Code
Response
The Organisation-level example returns:
Code
Working with secrets
For sensitive data like API keys, passwords, or tokens, set isSecret to true:
Code
Secret Variables:
- Can be resolved in supported text fields such as HTTP and MCP headers
- Are excluded from the rendering context used for SMS bodies and email subjects and bodies
The isSecret flag marks a value as sensitive; it is not a guarantee of field-level encryption or a reason to include credentials in spoken prompts.
Use cases
MCP server configuration
Store MCP server credentials as Secret Variables:
Code
Reference the Secret Variable in your MCP configuration's authorization header:
Code
Assistant instructions
Inject dynamic values into Assistant prompts:
Code
Constraints
-
Unique keys: Variable keys must be unique within the same scope (Organisation or Project). Attempting to create a duplicate key will return a
DUPLICATE_SECRET_KEYerror. -
Voice-call scope: The voice runtime loads Project Variables. Injected data and startup-request data can override ordinary Project Variable values for a call.
-
Value types: Values are stored as JSON. Strings are substituted directly; numbers, booleans, arrays and objects are rendered as JSON text when inserted into a template.
-
Key naming: Choose descriptive, consistent key names. Keys are case-sensitive, so
apiKeyandApiKeyare treated as different Variables.