Reecall
AI Assistants

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
{ key }

Example in Assistant instructions:

Code
You are a customer support agent for { companyName }.

If you have a Variable with key companyName:

JSONCode
{ "key": "companyName", "value": "Acme Corporation", "...": "other fields" }

It will be replaced at runtime:

Code
You are a customer support agent for Acme Corporation.

Variable entity structure

FieldTypeRequiredDescription
keystringYesThe reference name used in { key } syntax
valueJSON valueYesThe value to inject at runtime
isSecretbooleanNoWhen true, the value is treated as sensitive data
projectIdUUIDNoLinks 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
POST /core/variables Content-Type: application/json Authorization: Bearer <your-api-token> { "key": "companyName", "value": "Acme Corporation", "isSecret": false }

Project-level Variable

Create a Variable scoped to the Assistant's Project:

Code
POST /core/variables Content-Type: application/json Authorization: Bearer <your-api-token> { "key": "companyName", "value": "Acme Europe Division", "isSecret": false, "projectId": "b2c3d4e5-f6a7-8901-bcde-f23456789012" }

Response

The Organisation-level example returns:

JSONCode
{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "key": "companyName", "value": "Acme Corporation", "isSecret": false, "organizationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "projectId": null }

Working with secrets

For sensitive data like API keys, passwords, or tokens, set isSecret to true:

Code
POST /core/variables Content-Type: application/json Authorization: Bearer <your-api-token> { "key": "externalApiKey", "value": "sk-live-abc123xyz789", "isSecret": true, "projectId": "b2c3d4e5-f6a7-8901-bcde-f23456789012" }

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
POST /core/variables Content-Type: application/json Authorization: Bearer <your-api-token> { "key": "mcpApiToken", "value": "abc123xyz789", "isSecret": true, "projectId": "b2c3d4e5-f6a7-8901-bcde-f23456789012" }

Reference the Secret Variable in your MCP configuration's authorization header:

Code
POST /ai/mcp Content-Type: application/json Authorization: Bearer <your-api-token> { "name": "Example MCP", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer { mcpApiToken }" } }

Assistant instructions

Inject dynamic values into Assistant prompts:

Code
You are { assistantPersona }, a helpful assistant for { companyName }. When users ask about pricing, refer them to { pricingUrl }. Current promotion code: { promoCode }

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_KEY error.

  • 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 apiKey and ApiKey are treated as different Variables.

Last modified on