You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: fern/chat/variable-substitution.mdx
+5-181Lines changed: 5 additions & 181 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,8 +27,7 @@ When you create a session with `assistantOverrides.variableValues`, the system:
27
27
3. Stores the **pre-substituted assistant** in the session
28
28
4. Saves the original variable values in `session.metadata.variableValues` for reference
29
29
30
-
<CodeBlocks>
31
-
```bash title="cURL"
30
+
```bash title="Create session with variables"
32
31
curl -X POST https://api.vapi.ai/session \
33
32
-H "Authorization: Bearer $VAPI_API_KEY" \
34
33
-H "Content-Type: application/json" \
@@ -42,29 +41,6 @@ curl -X POST https://api.vapi.ai/session \
42
41
}
43
42
}'
44
43
```
45
-
```typescript title="TypeScript"
46
-
const session =awaitvapi.sessions.create({
47
-
assistantId: "your-assistant-id",
48
-
assistantOverrides: {
49
-
variableValues: {
50
-
name: "John",
51
-
company: "Acme Corp"
52
-
}
53
-
}
54
-
});
55
-
```
56
-
```python title="Python"
57
-
session = vapi.sessions.create(
58
-
assistant_id="your-assistant-id",
59
-
assistant_overrides={
60
-
"variableValues": {
61
-
"name": "John",
62
-
"company": "Acme Corp"
63
-
}
64
-
}
65
-
)
66
-
```
67
-
</CodeBlocks>
68
44
69
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"`.
70
46
@@ -84,9 +60,7 @@ When you send a chat request with a `sessionId`:
84
60
85
61
Once you set variables at session creation, they persist for all chats in that session:
86
62
87
-
<CodeBlocks>
88
-
```bash title="cURL"
89
-
# Chat using the session - variables already applied
63
+
```bash title="Chat using the session"
90
64
curl -X POST https://api.vapi.ai/chat \
91
65
-H "Authorization: Bearer $VAPI_API_KEY" \
92
66
-H "Content-Type: application/json" \
@@ -95,21 +69,6 @@ curl -X POST https://api.vapi.ai/chat \
95
69
"input": "What is my name and company?"
96
70
}'
97
71
```
98
-
```typescript title="TypeScript"
99
-
const chat =awaitvapi.chat.create({
100
-
sessionId: "session_xyz789",
101
-
input: "What is my name and company?"
102
-
});
103
-
// Response will reference "John" and "Acme Corp"
104
-
```
105
-
```python title="Python"
106
-
chat = vapi.chat.create(
107
-
session_id="session_xyz789",
108
-
input="What is my name and company?"
109
-
)
110
-
# Response will reference "John" and "Acme Corp"
111
-
```
112
-
</CodeBlocks>
113
72
114
73
The assistant will respond with the values set at session creation (John, Acme Corp).
115
74
@@ -119,9 +78,7 @@ The assistant will respond with the values set at session creation (John, Acme C
119
78
Passing new `variableValues` in a chat request **will not** change the session's pre-substituted assistant. The template placeholders no longer exist.
120
79
</Warning>
121
80
122
-
<CodeBlocks>
123
-
```bash title="cURL"
124
-
# This will NOT change the assistant's context
81
+
```bash title="This will NOT change the assistant's context"
125
82
curl -X POST https://api.vapi.ai/chat \
126
83
-H "Authorization: Bearer $VAPI_API_KEY" \
127
84
-H "Content-Type: application/json" \
@@ -136,44 +93,14 @@ curl -X POST https://api.vapi.ai/chat \
136
93
}
137
94
}'
138
95
```
139
-
```typescript title="TypeScript"
140
-
// This will NOT change the assistant's context
141
-
const chat =awaitvapi.chat.create({
142
-
sessionId: "session_xyz789",
143
-
input: "What is my name and company?",
144
-
assistantOverrides: {
145
-
variableValues: {
146
-
name: "Jane",
147
-
company: "Wayne Enterprises"
148
-
}
149
-
}
150
-
});
151
-
// Response will STILL reference "John" and "Acme Corp"
152
-
```
153
-
```python title="Python"
154
-
# This will NOT change the assistant's context
155
-
chat = vapi.chat.create(
156
-
session_id="session_xyz789",
157
-
input="What is my name and company?",
158
-
assistant_overrides={
159
-
"variableValues": {
160
-
"name": "Jane",
161
-
"company": "Wayne Enterprises"
162
-
}
163
-
}
164
-
)
165
-
# Response will STILL reference "John" and "Acme Corp"
166
-
```
167
-
</CodeBlocks>
168
96
169
97
The assistant still responds with "John" and "Acme Corp" because the original templates were already replaced.
170
98
171
99
### Provide fresh templates to use new values
172
100
173
101
To use different variable values mid-session, provide a new template with `{{ }}` placeholders along with the new values:
174
102
175
-
<CodeBlocks>
176
-
```bash title="cURL"
103
+
```bash title="Override with fresh template"
177
104
curl -X POST https://api.vapi.ai/chat \
178
105
-H "Authorization: Bearer $VAPI_API_KEY" \
179
106
-H "Content-Type: application/json" \
@@ -193,43 +120,6 @@ curl -X POST https://api.vapi.ai/chat \
193
120
}
194
121
}'
195
122
```
196
-
```typescript title="TypeScript"
197
-
const chat =awaitvapi.chat.create({
198
-
sessionId: "session_xyz789",
199
-
input: "What is my name and company?",
200
-
assistantOverrides: {
201
-
model: {
202
-
provider: "openai",
203
-
model: "gpt-4.1",
204
-
systemPrompt: "You are a helpful assistant for {{name}} at {{company}}. Be very formal."
205
-
},
206
-
variableValues: {
207
-
name: "Jane",
208
-
company: "Wayne Enterprises"
209
-
}
210
-
}
211
-
});
212
-
// Response will now reference "Jane" and "Wayne Enterprises"
213
-
```
214
-
```python title="Python"
215
-
chat = vapi.chat.create(
216
-
session_id="session_xyz789",
217
-
input="What is my name and company?",
218
-
assistant_overrides={
219
-
"model": {
220
-
"provider": "openai",
221
-
"model": "gpt-4.1",
222
-
"systemPrompt": "You are a helpful assistant for {{name}} at {{company}}. Be very formal."
223
-
},
224
-
"variableValues": {
225
-
"name": "Jane",
226
-
"company": "Wayne Enterprises"
227
-
}
228
-
}
229
-
)
230
-
# Response will now reference "Jane" and "Wayne Enterprises"
231
-
```
232
-
</CodeBlocks>
233
123
234
124
Now the assistant responds with "Jane" and "Wayne Enterprises" because fresh template placeholders were provided.
235
125
@@ -250,24 +140,7 @@ Now the assistant responds with "Jane" and "Wayne Enterprises" because fresh tem
250
140
251
141
### For consistent variables across a session
252
142
253
-
Pass `assistantOverrides.variableValues` once when creating the session. Subsequent chat requests only need the `sessionId` and `input`:
254
-
255
-
```typescript title="Recommended pattern"
256
-
// 1. Create session with variables
257
-
const session =awaitvapi.sessions.create({
258
-
assistantId: "your-assistant-id",
259
-
assistantOverrides: {
260
-
variableValues: {
261
-
customerName: "Sarah",
262
-
accountType: "Premium"
263
-
}
264
-
}
265
-
});
266
-
267
-
// 2. All chats use the session - variables persist
0 commit comments