Skip to content

Commit 3138813

Browse files
vapi-tasker[bot]claude
vapi-tasker[bot]
and
claude
authored
docs: add variable substitution behavior documentation for sessions and chat (#877)
* docs: add variable substitution behavior documentation for sessions and chat Explains how variableValues work when using sessions with the Chat API: - Variables are substituted at session creation and "baked in" - Subsequent chat requests cannot override with new variableValues - Fresh templates must be provided to use different values Includes code examples, quick reference table, and best practices. VAP-11219 Co-Authored-By: Claude <noreply@anthropic.com> * docs: add variable substitution page to Chat navigation VAP-11219 Co-Authored-By: Claude <noreply@anthropic.com> * docs: update model to gpt-4.1 and add LiquidJS reference - Changed all examples from gpt-4o-mini to gpt-4.1 - Added note explaining that Vapi uses LiquidJS for variable substitution - Clarified that {{ }} syntax follows Liquid template language conventions VAP-11219 Co-Authored-By: Claude <noreply@anthropic.com> * docs: simplify examples to cURL only Remove TypeScript and Python code examples, keeping only cURL for cleaner documentation. VAP-11219 Co-Authored-By: Claude <noreply@anthropic.com> * docs: use UUID format for example IDs Replace placeholder IDs with proper UUID format examples. VAP-11219 Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: vapi-tasker[bot] <253425205+vapi-tasker[bot]@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>
1 parent fd4fe10 commit 3138813

File tree

2 files changed

+174
-0
lines changed

2 files changed

+174
-0
lines changed

‎fern/chat/variable-substitution.mdx‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
title: Variable substitution in sessions
3+
subtitle: Learn how template variables behave with sessions and chats
4+
slug: chat/variable-substitution
5+
---
6+
7+
## Overview
8+
9+
When using sessions with the Chat API, understanding how variable substitution works is essential for building dynamic, personalized conversations.
10+
11+
**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.
12+
13+
<Note>
14+
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.
15+
</Note>
16+
17+
---
18+
19+
## How variable substitution works
20+
21+
### At session creation
22+
23+
When you create a session with `assistantOverrides.variableValues`, the system:
24+
25+
1. Takes your assistant's template variables (e.g., `"Hello {{name}} from {{company}}"`)
26+
2. Substitutes all `{{ }}` placeholders using LiquidJS
27+
3. Stores the **pre-substituted assistant** in the session
28+
4. Saves the original variable values in `session.metadata.variableValues` for reference
29+
30+
```bash title="Create session with variables"
31+
curl -X POST https://api.vapi.ai/session \
32+
-H "Authorization: Bearer $VAPI_API_KEY" \
33+
-H "Content-Type: application/json" \
34+
-d '{
35+
"assistantId": "79f3cae3-5e47-4d8c-a1b2-9f8e7d6c5b4a",
36+
"assistantOverrides": {
37+
"variableValues": {
38+
"name": "John",
39+
"company": "Acme Corp"
40+
}
41+
}
42+
}'
43+
```
44+
45+
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"`.
46+
47+
### At chat creation
48+
49+
When you send a chat request with a `sessionId`:
50+
51+
1. The system loads the session's pre-substituted assistant
52+
2. Any `variableValues` in the chat request are processed, but **there are no `{{ }}` placeholders left** to substitute
53+
3. New variable values have **no effect** on already-substituted text
54+
55+
---
56+
57+
## Behavior examples
58+
59+
### Variables persist across chats
60+
61+
Once you set variables at session creation, they persist for all chats in that session:
62+
63+
```bash title="Chat using the session"
64+
curl -X POST https://api.vapi.ai/chat \
65+
-H "Authorization: Bearer $VAPI_API_KEY" \
66+
-H "Content-Type: application/json" \
67+
-d '{
68+
"sessionId": "6b4c494f-c22c-4bce-84fa-a7a86942c7d3",
69+
"input": "What is my name and company?"
70+
}'
71+
```
72+
73+
The assistant will respond with the values set at session creation (John, Acme Corp).
74+
75+
### New variableValues don't override session values
76+
77+
<Warning>
78+
Passing new `variableValues` in a chat request **will not** change the session's pre-substituted assistant. The template placeholders no longer exist.
79+
</Warning>
80+
81+
```bash title="This will NOT change the assistant's context"
82+
curl -X POST https://api.vapi.ai/chat \
83+
-H "Authorization: Bearer $VAPI_API_KEY" \
84+
-H "Content-Type: application/json" \
85+
-d '{
86+
"sessionId": "6b4c494f-c22c-4bce-84fa-a7a86942c7d3",
87+
"input": "What is my name and company?",
88+
"assistantOverrides": {
89+
"variableValues": {
90+
"name": "Jane",
91+
"company": "Wayne Enterprises"
92+
}
93+
}
94+
}'
95+
```
96+
97+
The assistant still responds with "John" and "Acme Corp" because the original templates were already replaced.
98+
99+
### Provide fresh templates to use new values
100+
101+
To use different variable values mid-session, provide a new template with `{{ }}` placeholders along with the new values:
102+
103+
```bash title="Override with fresh template"
104+
curl -X POST https://api.vapi.ai/chat \
105+
-H "Authorization: Bearer $VAPI_API_KEY" \
106+
-H "Content-Type: application/json" \
107+
-d '{
108+
"sessionId": "6b4c494f-c22c-4bce-84fa-a7a86942c7d3",
109+
"input": "What is my name and company?",
110+
"assistantOverrides": {
111+
"model": {
112+
"provider": "openai",
113+
"model": "gpt-4.1",
114+
"systemPrompt": "You are a helpful assistant for {{name}} at {{company}}. Be very formal."
115+
},
116+
"variableValues": {
117+
"name": "Jane",
118+
"company": "Wayne Enterprises"
119+
}
120+
}
121+
}'
122+
```
123+
124+
Now the assistant responds with "Jane" and "Wayne Enterprises" because fresh template placeholders were provided.
125+
126+
---
127+
128+
## Quick reference
129+
130+
| Scenario | Variables applied? | Why |
131+
|----------|-------------------|-----|
132+
| Session creation with `variableValues` | ✅ Yes | Templates exist, substitution happens |
133+
| Chat with just `sessionId` | ✅ Session values persist | Pre-substituted assistant is used |
134+
| Chat with `sessionId` + new `variableValues` | ❌ No effect | No `{{ }}` placeholders left to substitute |
135+
| Chat with `sessionId` + new template with `{{ }}` + new `variableValues` | ✅ New values applied | Fresh templates provided |
136+
137+
---
138+
139+
## Best practices
140+
141+
### For consistent variables across a session
142+
143+
Pass `assistantOverrides.variableValues` once when creating the session. Subsequent chat requests only need the `sessionId` and `input`.
144+
145+
### For different variables per conversation
146+
147+
Choose one of these approaches:
148+
149+
<AccordionGroup>
150+
<Accordion title="Option A: Don't use sessions">
151+
Pass the full assistant configuration in each chat request. This gives you complete control over variables per request.
152+
</Accordion>
153+
<Accordion title="Option B: Override with fresh templates">
154+
Include a new system prompt (or other text field) with `{{ }}` placeholders plus new `variableValues` in your chat request.
155+
</Accordion>
156+
<Accordion title="Option C: Create separate sessions">
157+
Create a new session for each unique variable context. This keeps conversations cleanly separated.
158+
</Accordion>
159+
</AccordionGroup>
160+
161+
---
162+
163+
## Next steps
164+
165+
- **[Session management](/chat/session-management)** - Learn about `previousChatId` vs `sessionId` approaches
166+
- **[Variables](/assistants/dynamic-variables)** - Configure dynamic variables in your assistant
167+
- **[Streaming responses](/chat/streaming)** - Add real-time responses to your chats
168+
169+
<Callout>
170+
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).
171+
</Callout>

‎fern/docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -479,6 +479,9 @@ navigation:
479479
- page: Session management
480480
path: chat/session-management.mdx
481481
icon: fa-light fa-layer-group
482+
- page: Variable substitution
483+
path: chat/variable-substitution.mdx
484+
icon: fa-light fa-brackets-curly
482485
- page: SMS chat
483486
path: chat/sms-chat.mdx
484487
icon: fa-light fa-comment-sms

0 commit comments

Comments
 (0)