Variable substitution in sessions

Learn how template variables behave with sessions and chats

Overview

When using sessions with the Chat API, understanding how variable substitution works is essential for building dynamic, personalized conversations.

Key concept: Variables are substituted at session creation time and “baked into” the stored assistant configuration. Template placeholders like {{name}} are replaced with actual values and no longer exist in the session.

Vapi uses LiquidJS for variable substitution. The {{ }} syntax follows Liquid template language conventions, giving you access to filters, conditionals, and other Liquid features beyond simple variable replacement.

How variable substitution works

At session creation

When you create a session with assistantOverrides.variableValues, the system:

Takes your assistant’s template variables (e.g., "Hello {{name}} from {{company}}")
Substitutes all {{ }} placeholders using LiquidJS
Stores the pre-substituted assistant in the session
Saves the original variable values in session.metadata.variableValues for reference

Create session with variables

$ curl -X POST https://api.vapi.ai/session \
>   -H "Authorization: Bearer $VAPI_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "assistantId": "79f3cae3-5e47-4d8c-a1b2-9f8e7d6c5b4a",
>     "assistantOverrides": {
>       "variableValues": {
>         "name": "John",
>         "company": "Acme Corp"
>       }
>     }
>   }'

If your assistant’s system prompt was "You are a helpful assistant for {{name}} at {{company}}", the session stores: "You are a helpful assistant for John at Acme Corp".

At chat creation

When you send a chat request with a sessionId:

The system loads the session’s pre-substituted assistant
Any variableValues in the chat request are processed, but there are no {{ }} placeholders left to substitute
New variable values have no effect on already-substituted text

Behavior examples

Variables persist across chats

Once you set variables at session creation, they persist for all chats in that session:

Chat using the session

$ curl -X POST https://api.vapi.ai/chat \
>   -H "Authorization: Bearer $VAPI_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "sessionId": "6b4c494f-c22c-4bce-84fa-a7a86942c7d3",
>     "input": "What is my name and company?"
>   }'

The assistant will respond with the values set at session creation (John, Acme Corp).

New variableValues don’t override session values

Passing new variableValues in a chat request will not change the session’s pre-substituted assistant. The template placeholders no longer exist.

This will NOT change the assistant's context

$ curl -X POST https://api.vapi.ai/chat \
>   -H "Authorization: Bearer $VAPI_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "sessionId": "6b4c494f-c22c-4bce-84fa-a7a86942c7d3",
>     "input": "What is my name and company?",
>     "assistantOverrides": {
>       "variableValues": {
>         "name": "Jane",
>         "company": "Wayne Enterprises"
>       }
>     }
>   }'

The assistant still responds with “John” and “Acme Corp” because the original templates were already replaced.

Provide fresh templates to use new values

To use different variable values mid-session, provide a new template with {{ }} placeholders along with the new values:

Override with fresh template

$ curl -X POST https://api.vapi.ai/chat \
>   -H "Authorization: Bearer $VAPI_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "sessionId": "6b4c494f-c22c-4bce-84fa-a7a86942c7d3",
>     "input": "What is my name and company?",
>     "assistantOverrides": {
>       "model": {
>         "provider": "openai",
>         "model": "gpt-4.1",
>         "systemPrompt": "You are a helpful assistant for {{name}} at {{company}}. Be very formal."
>       },
>       "variableValues": {
>         "name": "Jane",
>         "company": "Wayne Enterprises"
>       }
>     }
>   }'

Now the assistant responds with “Jane” and “Wayne Enterprises” because fresh template placeholders were provided.

Quick reference

Scenario	Variables applied?	Why
Session creation with `variableValues`	✅ Yes	Templates exist, substitution happens
Chat with just `sessionId`	✅ Session values persist	Pre-substituted assistant is used
Chat with `sessionId` + new `variableValues`	❌ No effect	No `{{ }}` placeholders left to substitute
Chat with `sessionId` + new template with `{{ }}` + new `variableValues`	✅ New values applied	Fresh templates provided

Best practices

For consistent variables across a session

Pass assistantOverrides.variableValues once when creating the session. Subsequent chat requests only need the sessionId and input.

For different variables per conversation

Choose one of these approaches:

Option A: Don't use sessions

Pass the full assistant configuration in each chat request. This gives you complete control over variables per request.

Option B: Override with fresh templates

Include a new system prompt (or other text field) with {{ }} placeholders plus new variableValues in your chat request.

Option C: Create separate sessions

Create a new session for each unique variable context. This keeps conversations cleanly separated.

Next steps

Session management - Learn about previousChatId vs sessionId approaches
Variables - Configure dynamic variables in your assistant
Streaming responses - Add real-time responses to your chats

Need help? Chat with the team on our Discord or mention us on X/Twitter.

$	curl -X POST https://api.vapi.ai/session \
>	-H "Authorization: Bearer $VAPI_API_KEY" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"assistantId": "79f3cae3-5e47-4d8c-a1b2-9f8e7d6c5b4a",
>	"assistantOverrides": {
>	"variableValues": {
>	"name": "John",
>	"company": "Acme Corp"
>	}
>	}
>	}'

$	curl -X POST https://api.vapi.ai/chat \
>	-H "Authorization: Bearer $VAPI_API_KEY" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"sessionId": "6b4c494f-c22c-4bce-84fa-a7a86942c7d3",
>	"input": "What is my name and company?"
>	}'