Variable substitution in sessions
Learn how template variables behave with sessions and chats
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.
When you create a session with assistantOverrides.variableValues, the system:
"Hello {{name}} from {{company}}"){{ }} placeholders using LiquidJSsession.metadata.variableValues for referenceIf 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".
When you send a chat request with a sessionId:
variableValues in the chat request are processed, but there are no {{ }} placeholders left to substituteOnce you set variables at session creation, they persist for all chats in that session:
The assistant will respond with the values set at session creation (John, Acme Corp).
Passing new variableValues in a chat request will not change the session’s pre-substituted assistant. The template placeholders no longer exist.
The assistant still responds with “John” and “Acme Corp” because the original templates were already replaced.
To use different variable values mid-session, provide a new template with {{ }} placeholders along with the new values:
Now the assistant responds with “Jane” and “Wayne Enterprises” because fresh template placeholders were provided.
Pass assistantOverrides.variableValues once when creating the session. Subsequent chat requests only need the sessionId and input.
Choose one of these approaches:
Pass the full assistant configuration in each chat request. This gives you complete control over variables per request.
Include a new system prompt (or other text field) with {{ }} placeholders plus new variableValues in your chat request.
Create a new session for each unique variable context. This keeps conversations cleanly separated.
previousChatId vs sessionId approaches