Copy page

Guides

Per-Call Config Override

When you dispatch an outbound call, you can pass an agent_override object to modify the agent's configuration for that specific call only. The override is deep-merged on top of the agent's saved config and applies only to that call — the agent itself is unchanged.

This enables powerful use cases like personalized outbound calling, A/B testing different prompts, or switching voices for specific contact segments.

Basic Usage

Code
curl -X POST https://api.neuratel.ai/v1/voice-sessions/outbound \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "to_number": "+14155551234",
    "agent_override": {
      "brain": {
        "instructions": "You are calling {{contact.first_name}} about their upcoming renewal. Be warm and reference their account history."
      }
    }
  }'

Code
import httpx

httpx.post(
    "https://api.neuratel.ai/v1/voice-sessions/outbound",
    headers={"Authorization": "Bearer nk_live_your_api_key"},
    json={
        "agent_id": "agent_abc123",
        "to_number": "+14155551234",
        "agent_override": {
            "brain": {
                "instructions": "You are calling {{contact.first_name}} about their upcoming renewal."
            }
        }
    }
)

Code
await fetch("https://api.neuratel.ai/v1/voice-sessions/outbound", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agent_id: "agent_abc123",
    to_number: "+14155551234",
    agent_override: {
      brain: {
        instructions: "You are calling {{contact.first_name}} about their upcoming renewal."
      }
    }
  })
});

Override Examples

Switch Voice Provider

Code
{
  "agent_override": {
    "voice": {
      "provider": "cartesia",
      "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091",
      "model": "sonic-3",
      "language": "es"
    }
  }
}

Use Phantom Stack for Low Latency

Code
{
  "agent_override": {
    "brain": {
      "provider": "phantom",
      "model": "phantom"
    },
    "voice": {
      "provider": "phantom",
      "voice": "aria",
      "model": "phantom-english-speech-preview"
    },
    "transcriber": {
      "provider": "deepgram",
      "model": "nova-3"
    }
  }
}

Adjust Conversation Behavior

Code
{
  "agent_override": {
    "conversation": {
      "first_message": {
        "enabled": true,
        "text": "Hi {{contact.first_name}}, this is Alex from Acme Corp!"
      }
    }
  }
}

Reduce Max Tokens for Concise Responses

Code
{
  "agent_override": {
    "brain": {
      "max_completion_tokens": 150,
      "temperature": 0.6
    }
  }
}

How Overrides Are Applied

The agent_override is deep-merged on top of the agent's saved configuration:

• Nested objects are merged — you only need to specify the fields you want to change
• Arrays are replaced entirely — if you override mcp_servers, the array you provide replaces the saved one
• null values are skipped — to leave a field at its saved default, omit it from the override

Combining with Dynamic Variables

Overrides and dynamic variables work together. The agent's instructions (whether from the saved config or the override) can contain {{variable}} placeholders that are resolved from the dynamic_variables object:

Code
{
  "agent_id": "agent_abc123",
  "to_number": "+14155551234",
  "dynamic_variables": {
    "customer_name": "Sarah",
    "plan": "Pro",
    "renewal_date": "April 30"
  },
  "agent_override": {
    "brain": {
      "instructions": "You are calling {{customer_name}} about their {{plan}} plan renewal on {{renewal_date}}. Confirm they want to renew and update their preferred payment method."
    }
  }
}

Required Scope

agents:call

Related

• Dynamic Variables — inject contact data into prompts
• Outbound Campaigns — bulk calling
• Agents — full agent configuration reference