diff --git a/fern/chat/variable-substitution.mdx b/fern/chat/variable-substitution.mdx
new file mode 100644
index 000000000..980114349
--- /dev/null
+++ b/fern/chat/variable-substitution.mdx
@@ -0,0 +1,171 @@
+---
+title: Variable substitution in sessions
+subtitle: Learn how template variables behave with sessions and chats
+slug: chat/variable-substitution
+---
+
+## 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](https://liquidjs.com/) 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:
+
+1. Takes your assistant's template variables (e.g., `"Hello {{name}} from {{company}}"`)
+2. Substitutes all `{{ }}` placeholders using LiquidJS
+3. Stores the **pre-substituted assistant** in the session
+4. Saves the original variable values in `session.metadata.variableValues` for reference
+
+```bash title="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`:
+
+1. The system loads the session's pre-substituted assistant
+2. Any `variableValues` in the chat request are processed, but **there are no `{{ }}` placeholders left** to substitute
+3. 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:
+
+```bash title="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.
+
+
+```bash title="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:
+
+```bash title="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:
+
+
+
+ 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.
+
+
+
+---
+
+## Next steps
+
+- **[Session management](/chat/session-management)** - Learn about `previousChatId` vs `sessionId` approaches
+- **[Variables](/assistants/dynamic-variables)** - Configure dynamic variables in your assistant
+- **[Streaming responses](/chat/streaming)** - Add real-time responses to your chats
+
+
+Need help? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
+
diff --git a/fern/docs.yml b/fern/docs.yml
index 97e195f56..161594823 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -479,6 +479,9 @@ navigation:
- page: Session management
path: chat/session-management.mdx
icon: fa-light fa-layer-group
+ - page: Variable substitution
+ path: chat/variable-substitution.mdx
+ icon: fa-light fa-brackets-curly
- page: SMS chat
path: chat/sms-chat.mdx
icon: fa-light fa-comment-sms