For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Learn to choose between inline and stored assistant configurations
Overview
Choose between transient (inline) and permanent (stored) configurations to optimize your Vapi implementation for flexibility, reusability, and management needs.
In this guide, you’ll learn to:
Understand when to use transient vs permanent configurations
Implement both approaches with practical examples
Apply best practices for each configuration type
Key differences
Aspect
Transient
Permanent
Definition
Complete JSON in API request
ID reference to stored configuration
Storage
Exists only during API call
Stored on Vapi servers
Reusability
Defined per request
Reusable across multiple calls
Dashboard access
Not visible
Visible and manageable
Best for
Dynamic, personalized scenarios
Shared, reusable setups
Transient configurations
Use transient configurations when you need dynamic, call-specific behavior without pre-creating stored configurations.
When to use transient
Dynamic personalization
Best for: Customer-specific data Embed user information directly in
system messages
A/B testing
Best for: Configuration experiments Test different setups without
permanent storage
Temporary campaigns
Best for: Short-term promotions Event-specific assistants that don’t
need persistence
Development testing
Best for: Rapid prototyping Iterate quickly without managing stored
configs
Customer service with pre-filled data
1
{
2
"assistant": {
3
"name": "Customer Service Agent",
4
"model": {
5
"provider": "openai",
6
"model": "gpt-4o",
7
"messages": [
8
{
9
"role": "system",
10
"content": "You are a customer service representative for Acme Corp. The customer's name is John Smith and their account status is premium. Provide personalized assistance based on their business account history."
11
}
12
],
13
"temperature": 0.7
14
},
15
"voice": {
16
"provider": "11labs",
17
"voiceId": "N2lVS1w4EtoT3dr4eOWO"
18
},
19
"firstMessage": "Hello John, I see you're calling about your business account. How can I help you today?"
20
}
21
}
A/B testing scenario
1
{
2
"assistant": {
3
"name": "A/B Test Assistant - Variant A",
4
"model": {
5
"provider": "openai",
6
"model": "gpt-4",
7
"messages": [
8
{
9
"role": "system",
10
"content": "You are an enthusiastic sales representative. Use upbeat language and emphasize benefits."
11
}
12
],
13
"temperature": 0.9
14
},
15
"voice": {
16
"provider": "11labs",
17
"voiceId": "energetic-voice-id"
18
},
19
"firstMessage": "Hey there! Exciting news - I'd love to tell you about our amazing new features!",
20
"analysisPlan": {
21
"summaryPrompt": "Rate the customer's engagement level and interest in the product on a scale of 1-10.",
22
"structuredDataPlan": {
23
"enabled": true,
24
"schema": {
25
"type": "object",
26
"properties": {
27
"engagement_score": { "type": "number" },
28
"interest_level": {
29
"type": "string",
30
"enum": ["high", "medium", "low"]
31
},
32
"conversion_likelihood": { "type": "number" }
33
}
34
}
35
}
36
}
37
}
38
}
Transient tools
Create custom tools for specific integrations or workflows:
1
{
2
"tools": [
3
{
4
"type": "function",
5
"name": "check_inventory",
6
"description": "Check product inventory for the customer's specific region",
"content": "You are a technical support specialist for Enterprise Software. The customer has high priority issue."
22
}
23
]
24
},
25
"voice": {
26
"provider": "11labs",
27
"voiceId": "technical-voice-id"
28
}
29
},
30
"assistantDestinations": []
31
}
32
]
33
}
Best practices
Choosing the right approach
Use transient when:
Customer data needs to be embedded in system messages
Testing different configurations temporarily
Creating user-specific personalizations
Rapid prototyping and development
Use permanent when:
Multiple teams need access to the same configuration
Non-technical users manage configurations via dashboard
Consistency across multiple API calls is required
Version control and change tracking are important
Performance considerations
Transient: Slightly larger request payloads but no additional API calls
Permanent: Smaller request payloads but requires initial creation calls
Mixed: Optimize by using permanent for stable configs, transient for dynamic parts
Security and access control
Transient: Full configuration visible in API requests - avoid sensitive data
Permanent: Stored securely on Vapi servers with proper access controls
Recommendation: Use permanent configurations for sensitive integrations
Limitations
Transient limitations
Permanent limitations
No persistence: Cannot retrieve or reuse after API call - No
dashboard access: Not visible in Vapi dashboard - No version control:
Cannot track configuration changes - Request size: Larger payloads may
impact performance
Next steps
Now that you understand transient vs permanent configurations:
