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.

Implementation status (2026-10-04). Parts of this page describe a design that was never built. They are kept, and marked not implemented, because their reasoning informs the planned verified-variables work. See docs/agentic-development/CHORES.md C-210.

Implemented: variables in POST /bots/:id/chat and POST /bots/:id/conversations (and the public POST /public/agents/:slug/conversations); the pre-chat visitor form; agent-level and system defaults; the precedence merge; rendering.
Not implemented: signed context tokens. contextToken is accepted by the conversation-create schemas and forwarded by packages/chat-core, but nothing issues, verifies or reads one, and there is no POST /bots/:id/context-token endpoint.
Not implemented: setting sensitive variables. There is no POST .../conversations/:conversationId/variables endpoint, and nothing calls conversationVariablesRepository.setSensitiveVariables, so the encrypted sensitive_variables store is read during rendering but never written.
Not implemented: var_ query parameters on chat links, and the widget’s data-variables / data-context-token attributes. Nothing in apps/web or embed.js reads them.

Variable values that do arrive are supplied by the visitor or the API caller and are not verified; do not use them for anything that must be trusted.

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 (not implemented, nothing writes them — C-210)	Designed: `POST .../variables` endpoint or signed context token	User PII, account IDs, internal tier
3	Client-set invocation variables	Visitor form, API body when the conversation is created or on the first message (query params and widget config: not implemented)	User name, 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 (not implemented)
Web Widget (not implemented)

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" }
}

The schema also accepts contextToken, but it currently has no effect (not implemented — C-210).

Not implemented — nothing reads var_ parameters (C-210). Design: 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.

Not implemented — embed.js reads neither attribute (C-210). Design:

<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 (not implemented)

Design only — not implemented (C-210). The conversation_variables.sensitive_variables column and its decryption on read exist, but neither write path below was built: there is no POST .../variables endpoint and no context-token issuer or verifier. The design is kept for the planned verified-variables work.

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 (not implemented)

Design: 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 (not implemented)

Design: 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. (The intended remedy, signed context tokens, is not implemented — C-210. Until it is, there is no safe channel for sensitive values: keep them out of variables.)
Variables are not verified: a value arrives as the visitor or API caller sent it. Never use one to decide anything that must be trusted, such as a customer tier that unlocks behaviour.
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 (design, not implemented): a token should carry a reasonable expires_in (e.g., 3600 seconds) and be rejected once expired.
Sensitive variables (design, write path not implemented): encrypted at rest, never returned in GET responses, only accessible server-side during prompt rendering.
Query param variables (not implemented): 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 (not implemented)

Setting via POST Endpoint (not implemented)

Setting via Signed Context Token (not implemented)

Resolution Flow

Prompt Rendering Engine

Per-Message Variable Overrides

Security Considerations

​Overview

​Variable Syntax

​Sources and Precedence

​Passing Variables

​Sensitive Variables (not implemented)

​Setting via POST Endpoint (not implemented)

​Setting via Signed Context Token (not implemented)

​Resolution Flow

​Prompt Rendering Engine

​Per-Message Variable Overrides

​Security Considerations

Overview

Variable Syntax

Sources and Precedence

Passing Variables

Sensitive Variables (not implemented)

Setting via POST Endpoint (not implemented)

Setting via Signed Context Token (not implemented)

Resolution Flow

Prompt Rendering Engine

Per-Message Variable Overrides

Security Considerations