Dynamic Variables

Overview

Dynamic variables allow prompt templates to be personalized at runtime using data from multiple sources. Variables use Mustache-style {{variable_name}} syntax and are resolved from a priority-ordered chain of sources before any prompt is rendered.

Variable Syntax

Hi {{user_name}}! Welcome to {{bot_name}}.
Your current plan is {{plan_tier}}.

Variable names are case-sensitive
Unresolved variables are replaced with an empty string
Unresolved variables are logged as warnings for debugging
Nested/escaped braces are handled gracefully

Sources and Precedence

Variables are merged from highest to lowest priority (higher priority overwrites lower for the same key):

Priority	Source	Set By	Example
1	Per-message overrides	API body `variables` on subsequent messages	Updating page context mid-conversation
2	Server-set sensitive variables	`POST .../variables` endpoint or signed context token	User PII, account IDs, internal tier
3	Client-set invocation variables	Query params, widget config, API body on first message	User name, plan tier, referral source
4	Agent-level defaults	Bot’s `prompt_variables` configuration	Default greeting name, brand name
5	System defaults	Platform-wide `default_variables` in platform_config	Generic fallbacks

Passing Variables

Chat Request
Conversation Creation
Direct Link
Web Widget

Include variables in the chat request body:

POST /bots/:id/chat
{
  "message": "Hello",
  "variables": { "user_name": "John", "plan": "pro" },
  "conversationId": "...",
  "stream": false
}

First request (no conversationId): variables stored as initial_variables and variables
Subsequent requests: new variables merged into variables (existing keys overwritten)

POST /bots/:id/conversations
{
  "variables": { "user_name": "John", "plan": "pro" },
  "context_token": "eyJ..."
}

Pass non-sensitive variables via query params using the var_ prefix:

/chat/bot-id?var_user_name=John&var_plan=pro

Frontend strips the var_ prefix and passes variables to the first chat request.

<script
  data-bot-id="abc"
  data-variables='{"user_name":"John","plan":"pro"}'
  data-context-token="eyJ..."
  src="https://widget.brainstormer.ai/embed.js">
</script>

data-variables: non-sensitive client variables (exposed in HTML source)
data-context-token: signed JWT from host backend (for sensitive vars)

Sensitive Variables

Sensitive variables are server-set and never returned in any client-facing API response. They are stored encrypted in conversation_variables.sensitive_variables using AES-256-GCM.

Setting via POST Endpoint

Call from your backend before or during the conversation:

POST /bots/:id/conversations/:conversationId/variables
{
  "sensitive": true,
  "variables": { "account_id": "12345", "internal_tier": "enterprise" }
}

Setting via Signed Context Token

Generate a signed JWT from your backend:

POST /bots/:id/context-token
{
  "variables": { "user_name": "John", "account_id": "12345" },
  "sensitive_keys": ["account_id"],
  "expires_in": 3600
}

Response: { "token": "eyJ..." }

Frontend receives opaque token, passes as context_token in conversation create or chat request
Bot service decodes JWT server-side, extracts variables
Keys listed in sensitive_keys are stored encrypted; others stored as regular variables
Token has expiry — validated before use

Use case: Host backend pre-generates context for an embedded widget session. The frontend never sees the sensitive values, only the opaque token.

Resolution Flow

Prompt Rendering Engine

Shared utility in packages/shared/src/prompt-renderer.ts:

interface RenderResult {
  rendered: string;
  unresolvedVariables: string[];
}

function renderPrompt(
  template: string,
  variables: Record<string, string>
): RenderResult;

Pure function, no side effects
Used by bot service for all prompt types
Handles nested/escaped braces gracefully
Returns list of unresolved variables for logging

Per-Message Variable Overrides

Variables can be updated mid-conversation by including variables in any chat request:

POST /bots/:id/chat
{
  "message": "Now show me the enterprise options",
  "conversationId": "existing-conv-id",
  "variables": { "current_page": "pricing", "plan": "enterprise" }
}

New variables are merged into the existing conversation_variables.variables record, enabling dynamic context updates as the conversation progresses.

Security Considerations

Follow these security rules for all variable handling.

Never expose sensitive variable keys in client-side code or HTML. Use signed context tokens.
Prompt injection: Malicious variable values could attempt to override LLM behavior. Variables should be clearly delimited (e.g., wrapped in quotes or XML tags) when inserted into LLM prompts.
Context token expiry: Always set a reasonable expires_in (e.g., 3600 seconds). Expired tokens are rejected.
Sensitive variables: Encrypted at rest, never returned in GET responses, only accessible server-side during prompt rendering.
Query param variables: Only use for non-sensitive data — query params are logged and visible in browser history.

Overview

Services

Architecture

Agent Provisioning API

Deployment

Design System (Neo)

Overview

Variable Syntax

Sources and Precedence

Passing Variables

Sensitive Variables

Setting via POST Endpoint

Setting via Signed Context Token

Resolution Flow

Prompt Rendering Engine

Per-Message Variable Overrides

Security Considerations

​Overview

​Variable Syntax

​Sources and Precedence

​Passing Variables

​Sensitive Variables

​Setting via POST Endpoint

​Setting via Signed Context Token

​Resolution Flow

​Prompt Rendering Engine

​Per-Message Variable Overrides

​Security Considerations

Overview

Variable Syntax

Sources and Precedence

Passing Variables

Sensitive Variables

Setting via POST Endpoint

Setting via Signed Context Token

Resolution Flow

Prompt Rendering Engine

Per-Message Variable Overrides

Security Considerations