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

# Variables

> How built-in and custom variables work in agent system prompts.

## Overview

Echo's variable system lets you write a single agent prompt that works for any customer and any call scenario. Use `{{variable_name}}` syntax anywhere in your `system_prompt` — Echo resolves the values before the call is initiated.

```text theme={null}
"Hi {{recipient_first_name}}, I'm calling from {{business_name}} about your {{appointment_type}} on {{appointment_time}}."
```

***

## Built-in Variables

Echo automatically resolves these from your business account and the customer record. You never need to pass them in `variables`.

| Variable                   | Source               | Value                              |
| -------------------------- | -------------------- | ---------------------------------- |
| `{{business_name}}`        | Business             | Your business name from signup     |
| `{{business_summary}}`     | Business             | Your business summary from signup  |
| `{{industry}}`             | Business             | Your industry from signup          |
| `{{recipient_name}}`       | Customer             | Full name (`first_name last_name`) |
| `{{recipient_first_name}}` | Customer             | Customer's first name              |
| `{{message}}`              | Notification request | The `message` field                |
| `{{context}}`              | Notification request | The `context` field (optional)     |

***

## Custom Variables

Any `{{token}}` that isn't in the built-in list must be supplied in the `variables` map when triggering a notification.

```text System prompt theme={null}
"...your appointment at {{appointment_time}} with {{doctor_name}}. Tone: {{tone}}."
                               ↑ custom                  ↑ custom           ↑ custom
```

```json Notification request theme={null}
{
  "customer_id": "...",
  "agent_id": "...",
  "variables": {
    "appointment_time": "Thursday March 20th at 2:00 PM",
    "doctor_name": "Dr. Patel",
    "tone": "warm and professional"
  }
}
```

Custom variables can be any string values you want. There's no predefined list — anything you put in `variables` becomes available as `{{key}}` in the prompt.

***

## Override Behavior

If a caller-provided variable and a built-in share the same name, the caller-provided value wins.

```json theme={null}
"variables": {
  "recipient_first_name": "Johnny"
}
```

This overrides the built-in `{{recipient_first_name}}` with `"Johnny"` for this specific call.

***

## Missing Variables

If a `{{token}}` appears in the system prompt but has no corresponding value (neither built-in nor custom), the token is left as-is in the rendered prompt — which will cause the AI to read out `{{token_name}}` literally.

To avoid this:

* Check that every `{{token}}` in your prompt is either a built-in or included in `variables`
* Use the [prompt checklist](/guides/writing-prompts#prompt-checklist) before going to production

***

## Variable Resolution Order

```
1. Built-in variables (auto-resolved from business + customer records)
2. Notification-time variables (from the "variables" map in the request)
   └── Overrides built-ins on name collision
```

***

## Examples by Use Case

<AccordionGroup>
  <Accordion title="Appointment reminder">
    ```json theme={null}
    "variables": {
      "appointment_time": "Friday April 4th at 3:30 PM",
      "doctor_name": "Dr. Kim",
      "location": "Suite 200, 450 Medical Plaza"
    }
    ```

    ```text Prompt excerpt theme={null}
    "Your appointment with {{doctor_name}} is on {{appointment_time}} at {{location}}."
    ```
  </Accordion>

  <Accordion title="Trial expiration warning">
    ```json theme={null}
    "variables": {
      "days_remaining": "2",
      "plan_name": "Pro",
      "upgrade_url": "app.yourcompany.com/upgrade"
    }
    ```

    ```text Prompt excerpt theme={null}
    "Your {{plan_name}} trial ends in {{days_remaining}} days. Visit {{upgrade_url}} to keep access."
    ```
  </Accordion>

  <Accordion title="Delivery notification">
    ```json theme={null}
    "variables": {
      "order_number": "ORD-88231",
      "delivery_date": "tomorrow between 2 PM and 6 PM",
      "carrier": "FedEx"
    }
    ```

    ```text Prompt excerpt theme={null}
    "Order {{order_number}} is out for delivery via {{carrier}}. Expected: {{delivery_date}}."
    ```
  </Accordion>

  <Accordion title="Per-call tone adjustment via context">
    ```json theme={null}
    "context": "This customer has called support twice this week. Be extra patient and apologetic."
    ```

    ```text Prompt excerpt theme={null}
    "Additional context for this call: {{context}}"
    ```
  </Accordion>
</AccordionGroup>