Skip to navigation
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

{
  "assistant": {
    "name": "Customer Service Agent",
    "model": {
      "provider": "openai",
      "model": "gpt-4o",
      "messages": [
        {
          "role": "system",
          "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."
        }
      ],
      "temperature": 0.7
    },
    "voice": {
      "provider": "11labs",
      "voiceId": "N2lVS1w4EtoT3dr4eOWO"
    },
    "firstMessage": "Hello John, I see you're calling about your business account. How can I help you today?"
  }
}

A/B testing scenario

{
  "assistant": {
    "name": "A/B Test Assistant - Variant A",
    "model": {
      "provider": "openai",
      "model": "gpt-4",
      "messages": [
        {
          "role": "system",
          "content": "You are an enthusiastic sales representative. Use upbeat language and emphasize benefits."
        }
      ],
      "temperature": 0.9
    },
    "voice": {
      "provider": "11labs",
      "voiceId": "energetic-voice-id"
    },
    "firstMessage": "Hey there! Exciting news - I'd love to tell you about our amazing new features!",
    "analysisPlan": {
      "summaryPrompt": "Rate the customer's engagement level and interest in the product on a scale of 1-10.",
      "structuredDataPlan": {
        "enabled": true,
        "schema": {
          "type": "object",
          "properties": {
            "engagement_score": { "type": "number" },
            "interest_level": {
              "type": "string",
              "enum": ["high", "medium", "low"]
            },
            "conversion_likelihood": { "type": "number" }
          }
        }
      }
    }
  }
}

Transient tools

Add call-specific tools directly to a transient assistant’s model configuration.

The API Request tool sends the model-generated body directly to the configured URL. Replace YOUR_CREDENTIAL_ID with a Vapi Custom Credential that authenticates the request without placing a secret in the tool definition.

The following examples are assistant.model fragments:

{
  "tools": [
    {
      "type": "apiRequest",
      "name": "check_inventory",
      "description": "Check product inventory for the customer's specific region",
      "method": "POST",
      "url": "https://api.example.com/inventory/check",
      "credentialId": "YOUR_CREDENTIAL_ID",
      "timeoutSeconds": 30,
      "body": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string",
            "description": "The product ID to check"
          },
          "region": {
            "type": "string",
            "description": "The customer's region code"
          }
        },
        "required": ["productId", "region"]
      }
    }
  ]
}

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 tool

Store the reusable tool on Vapi servers and copy its ID.

2

Create the assistant

Add the tool ID to the assistant’s model configuration and copy the assistant ID.

3

Create calls with the assistant

Reference the stored assistant by its ID.

curl -X POST "https://api.vapi.ai/tool" \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "apiRequest",
    "name": "update_crm_contact",
    "description": "Update contact information in the CRM system",
    "method": "POST",
    "url": "https://api.example.com/contacts/update",
    "credentialId": "YOUR_CREDENTIAL_ID",
    "body": {
      "type": "object",
      "properties": {
        "contactId": {
          "type": "string",
          "description": "The CRM contact ID"
        },
        "updates": {
          "type": "object",
          "description": "The contact fields and values to update"
        }
      },
      "required": ["contactId", "updates"]
    }
  }'

Replace the tool, credential, and assistant ID placeholders with values from the resources you created. The credential authenticates the API Request tool’s call to the CRM endpoint.

Mixed configurations

Combine transient and permanent configurations for maximum flexibility:

{
  "squad": [
    {
      "assistantId": "permanent-receptionist-assistant-id",
      "assistantDestinations": [
        {
          "type": "assistant",
          "assistantName": "technical-support"
        }
      ]
    },
    {
      "assistant": {
        "name": "technical-support",
        "model": {
          "provider": "openai",
          "model": "gpt-4",
          "messages": [
            {
              "role": "system",
              "content": "You are a technical support specialist for Enterprise Software. The customer has high priority issue."
            }
          ]
        },
        "voice": {
          "provider": "11labs",
          "voiceId": "technical-voice-id"
        }
      },
      "assistantDestinations": []
    }
  ]
}

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: