> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pre-call Variables

> Template per-call data into your agent's prompt and greeting with `{{name}}` placeholders

# Pre-call Variables

Pre-call variables let you template the agent's prompt and greeting with per-call data. You declare a list of variable *names* on the agent (`callee_name`, `mobile_number`), supply per-call *values* via the API or sandbox, and the platform substitutes `{{name}}` references in `Agent.prompt` + `Agent.greeting` before the bot starts.

<Info>
  **Partner API (v2) only** for the endpoints below.
</Info>

## 1. Declare the variable names on the agent

```bash theme={null}
PUT /api/v2/agent/{id}
Authorization: Bearer rg_live_...
Content-Type: application/json

{
  "variables": ["callee_name", "mobile_number"]
}
```

Names must match `^[a-zA-Z_][a-zA-Z0-9_]*$` (no spaces, dashes, or special characters). Up to 100 variables per agent. Pass `null` to clear the list.

## 2. Reference them in the prompt or greeting

The agent's `prompt` and `intro_message` accept `{{name}}` placeholders. Whitespace inside the braces is tolerated (`{{ name }}` works the same as `{{name}}`).

```text theme={null}
You are calling {{callee_name}} regarding their order. Be friendly,
acknowledge them by name, and confirm we're reaching them on
{{mobile_number}}.
```

```text theme={null}
Hi {{callee_name}}, this is your friendly assistant.
```

## 3. Supply per-call values

Include `connection_id` when your account has multiple active connections for the selected provider.

```bash theme={null}
POST /api/v2/calls/start
Authorization: Bearer rg_live_...
Content-Type: application/json

{
  "agent_id": "...",
  "to_number": "+919876543210",
  "provider": "twilio",
  "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
  "variables": {
    "callee_name": "Sajal",
    "mobile_number": "+919876543210"
  }
}
```

## 4. Echoed in the webhook

The `session.completed` webhook echoes the same `variables` map for partner-side audit. See [Webhook Payloads](/webhooks/payloads) for the full payload shape.

## Behavior

* **Missing values render as empty strings.** A prompt that says `Hi {{callee_name}}!` produces `Hi !` if `callee_name` is omitted. The platform never errors on missing variables.
* **Type coercion is automatic.** Non-string values in the request body (`{ age: 25 }`, `{ active: true }`) are stringified before substitution.
* **Inbound calls** receive no `variables` field by default; placeholders in the prompt render empty.
* **Custom functions can read variables.** Values supplied at call start are available to your configured custom functions, so handlers such as CRM lookup or calendar booking can use fields like `customer_id` directly.

## Next steps

<CardGroup cols={2}>
  <Card title="Post-call Extraction" icon="wand-magic-sparkles" href="/post-call-extraction">
    Pull structured fields out of completed call transcripts with an LLM-driven analyzer.
  </Card>

  <Card title="Webhook Payloads" icon="bell" href="/webhooks/payloads">
    Full reference for the `session.completed` payload, including the `variables` echo.
  </Card>
</CardGroup>