AssistantsCore concepts

Transient vs permanent configurations

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

AspectTransientPermanent
DefinitionComplete JSON in API requestID reference to stored configuration
StorageExists only during API callStored on Vapi servers
ReusabilityDefined per requestReusable across multiple calls
Dashboard accessNot visibleVisible and manageable
Best forDynamic, personalized scenariosShared, 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",
7      "parameters": {
8        "type": "object",
9        "properties": {
10          "productId": {
11            "type": "string",
12            "description": "The product ID to check"
13          },
14          "region": {
15            "type": "string",
16            "description": "Customer's region code"
17          }
18        },
19        "required": ["productId", "region"]
20      },
21      "server": {
22        "url": "https://api.customer-integration.com/inventory",
23        "secret": "customer-webhook-secret",
24        "timeoutSeconds": 30
25      }
26    }
27  ]
28}

Transient limitations: Configurations exist only during the API call and cannot be managed through the dashboard or reused across calls.

Permanent configurations

Use permanent configurations for reusable setups that multiple teams can access and manage through the dashboard.

When to use permanent

Shared resources

Best for: Team collaboration Assistants used across multiple departments

Dashboard management

Best for: Non-technical users Visual configuration management

Reusable setups

Best for: Standard workflows Consistent configurations across calls

Version control

Best for: Change tracking Maintain configuration history

Creating permanent configurations

1

Create the assistant

Store your assistant configuration on Vapi servers

2

Get the assistant ID

Use the returned UUID to reference the assistant

3

Reference in API calls

Use the ID instead of inline configuration

$curl -X POST "https://api.vapi.ai/assistant" \
>  -H "Authorization: Bearer $VAPI_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "General Support Assistant",
>    "model": {
>      "provider": "openai",
>      "model": "gpt-4",
>      "messages": [
>        {
>          "role": "system",
>          "content": "You are a helpful customer service representative for Acme Corp. Provide accurate information about our products and services."
>        }
>      ]
>    },
>    "voice": {
>      "provider": "11labs",
>      "voiceId": "N2lVS1w4EtoT3dr4eOWO"
>    },
>    "firstMessage": "Hello! Thank you for calling Acme Corp. How can I assist you today?"
>  }'

Mixed configurations

Combine transient and permanent configurations for maximum flexibility:

1{
2  "squad": [
3    {
4      "assistantId": "permanent-receptionist-assistant-id",
5      "assistantDestinations": [
6        {
7          "type": "assistant",
8          "assistantName": "technical-support"
9        }
10      ]
11    },
12    {
13      "assistant": {
14        "name": "technical-support",
15        "model": {
16          "provider": "openai",
17          "model": "gpt-4",
18          "messages": [
19            {
20              "role": "system",
21              "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

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
  • 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
  • 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

  • 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: