> This page is for SWML.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Variables

> Syntax, scopes, deployment modes, and how to access nested data with SWML variables.

SWML provides a variable system for accessing call or message information, storing intermediate
state, and passing data between sections. This page covers **how to use** variables: syntax,
scopes, accessing nested fields, and deployment-mode differences.

For the authoritative field-by-field reference of what each scope contains, see the per-flavor
overviews:

* [Calling webhook and variable payload](/docs/swml/reference/calling#webhook-payload) — `call`, `params`, `vars`, `envs`
* [Messaging webhook and variable payload](/docs/swml/reference/messaging#webhook-payload) — `message`, `params`, `vars`

For JavaScript expressions on top of variables, see [Expressions](/docs/swml/reference/expressions).
For template transformation functions, see [Template Functions](/docs/swml/reference/template-functions).

## Syntax

Wrap a variable name in `${...}` or `%{...}` anywhere inside a string value, and SignalWire
substitutes the current value when the script runs. Use it to personalize a greeting with the
caller's number, pass a request body through to your backend, or pick a reply based on the
inbound message body.

The two flavors of SWML accept slightly different forms.

### Calling

In a Calling document, `${...}` and `%{...}` are interchangeable — pick whichever reads more
naturally in your YAML or JSON.

**Reference a value.** Use a plain path like `${call.from}` or `%{vars.user_choice}`. Works
for any field on `call`, `params`, `envs`, or `vars`. If the path is valid but the value isn't
set, the placeholder resolves to an empty string.

If the placeholder body isn't a plain path — for example, it includes operators, method
calls, or other JavaScript — it's evaluated as a JavaScript expression instead. See
[Expressions](/docs/swml/reference/expressions).

#### YAML

```yaml
version: 1.0.0
sections:
  main:
    - play:
        url: 'say: This call is from ${call.from}'
```

#### JSON

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      { "play": { "url": "say: This call is from ${call.from}" } }
    ]
  }
}
```

### Messaging

A Messaging document uses `%{...}` only.

**Reference a value.** Use a plain path like `%{message.from}` or `%{vars.reply_message_id}`.
Works for any field on `message`, `params`, or `vars`. If the path is valid but the value
isn't set, the placeholder resolves to an empty string.

#### YAML

```yaml
version: 1.0.0
sections:
  main:
    - reply:
        body: 'Received message from %{message.from}: %{message.body}'
```

#### JSON

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      { "reply": { "body": "Received message from %{message.from}: %{message.body}" } }
    ]
  }
}
```

## Variable scopes

The variables available at runtime are the same fields delivered on the inbound webhook payload
for each SWML flavor. See the
[Calling webhook and variable payload](/docs/swml/reference/calling#webhook-payload) and the
[Messaging webhook and variable payload](/docs/swml/reference/messaging#webhook-payload) for the
authoritative list of scopes (`call` / `message`, `params`, `vars`, `envs`) and every field
inside them.

## Variables an AI agent reads

**`ai_response`** `string`

Tells an AI agent what happened after a SWAIG function's [`SWML` action](/docs/swml/reference/calling/ai/swaig/functions#actionswml) runs on the call. When that SWML finishes, the agent reads `ai_response`, fills in any `${...}` variables it contains, adds the text to the conversation as an instruction, and replies right away without waiting for the caller. The variable is then cleared, so each value is used once.

If it isn't set, results from the SWML (such as `pay_result` or `prompt_value`) don't reach the agent, apart from changes to `global_data` when [`persist_global_data`](/docs/swml/reference/calling/ai/params#paramspersist_global_data) is on.

Set it with [`set`](/docs/swml/reference/calling/set) after the method whose result it reports, because `set` fills in variables when it runs. It applies only when the SWML runs in place, not when the action's `transfer` is `true`.

---

## Accessing nested data

Variables can hold simple values, nested objects, or arrays. Use dot notation (`.`) for object
properties and bracket notation (`[]`, zero-based) for array elements. The patterns below work
identically inside `${...}` and `%{...}`; the examples use calling syntax and the
[`set`](/docs/swml/reference/calling/set) method to seed the data.

#### YAML

```yaml
version: 1.0.0
sections:
  main:
    - set:
        user:
          name: Alice
          address:
            city: Seattle
        employees:
          - name: Alice
            role: Engineer
          - name: Bob
            role: Manager
    - play:
        url: 'say: ${user.name} lives in ${user.address.city}'
    - play:
        url: 'say: ${employees[0].name} is an ${employees[0].role}'
    - play:
        url: 'say: ${employees[1].name} is a ${employees[1].role}'
```

#### JSON

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "set": {
          "user": {
            "name": "Alice",
            "address": { "city": "Seattle" }
          },
          "employees": [
            { "name": "Alice", "role": "Engineer" },
            { "name": "Bob", "role": "Manager" }
          ]
        }
      },
      { "play": { "url": "say: ${user.name} lives in ${user.address.city}" } },
      { "play": { "url": "say: ${employees[0].name} is an ${employees[0].role}" } },
      { "play": { "url": "say: ${employees[1].name} is a ${employees[1].role}" } }
    ]
  }
}
```

The same patterns apply in messaging — for example, `%{message.media[0].url}` accesses the
first media attachment's URL.

## Deployment modes

SWML can be hosted in two places, which affects how variable values get into your script.

### Serverless (Dashboard-hosted)

The SWML document lives in the SignalWire Dashboard. SignalWire evaluates the placeholders
against the live runtime context — no HTTP fetch is involved.

#### YAML

```yaml
version: 1.0.0
sections:
  main:
    - set:
        department: sales
    - play:
        url: 'say: You are calling from ${call.from}'
    - play:
        url: 'say: Department is ${vars.department}'
```

#### JSON

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      { "set": { "department": "sales" } },
      { "play": { "url": "say: You are calling from ${call.from}" } },
      { "play": { "url": "say: Department is ${vars.department}" } }
    ]
  }
}
```

### Server-based (external URL)

SignalWire POSTs the runtime context to your server and your server returns the SWML document
in response (see the [Calling](/docs/swml/reference/calling#webhook-payload) or
[Messaging](/docs/swml/reference/messaging#webhook-payload) payload reference for the request
shape). You have two ways to use the variables:

**1. Return SWML with placeholders.** SignalWire substitutes at runtime — exactly the same
syntax used in serverless mode. Best when you just need to interpolate values into
otherwise-static SWML.

**2. Substitute server-side before responding.** Read variables from the request body in your
server code, then build a SWML document with the values already filled in. Best when you need
logic, transformations, or external lookups that can't be expressed as a placeholder.

> **Note**
>
> The `${...}` in the example below is **JavaScript template-literal syntax**, not SWML
> variable expansion — it's interpolated by Node.js before the response is sent.

```javascript
// Example: Node.js / Express server
app.post('/swml-handler', (req, res) => {
  const { call, vars, envs, params } = req.body;

  // Pull values out of the request and apply your own logic
  const department = params.department || 'support';
  const callerNumber = call.from;

  // Build SWML with concrete values already substituted
  res.json({
    version: '1.0.0',
    sections: {
      main: [
        { play: { url: `say: Welcome to ${department}` } },
        { play: { url: `say: Calling from ${callerNumber}` } },
      ],
    },
  });
});
```

See the [Deployment Guide](/docs/swml/guides/deployment) for complete server setup instructions.