Variables

SWML provides a powerful variable system that allows you to access call information, store data, and pass parameters between sections. This page is the authoritative technical reference for global variable scopes (call, params, vars, envs) and variable management in SWML.

For information about using JavaScript expressions with variables, see the Expressions Reference. For template transformation functions, see the Template Functions Reference.

Syntax

SWML uses the ${variable} syntax for variable substitution:

1
version: 1.0.0
2
sections:
3
  main:
4
    - play:
5
        url: 'say: This call is from the number ${call.from}'

Reference

SWML provides several variable scopes that are available throughout your scripts. These scopes give you access to call information, script parameters, and stored data.

Scope: Account/project-level and read-only. Set in your SignalWire account configuration, not within SWML scripts.

Fallback behavior: When you reference a variable without a scope prefix (e.g., ${my_variable}), SWML first checks vars. If not found in vars, it automatically falls back to envs.

Example keys: envs.api_key, envs.webhook_url, envs.account_setting

Scope: Section-scoped and read-only. Each section has its own independent params that must be explicitly passed via execute or transfer. Params do not persist after a section completes. When an execute call returns, the calling section’s original params are restored.

Example keys: params.audio_file, params.volume, params.department

Created by:

• set method - Create or update user-defined variables
• Method outputs - Many methods automatically create variables (e.g., prompt_value, record_url, return_value)

Managed with:

• unset method - Remove variables

Example keys: vars.user_choice, vars.counter, vars.prompt_value, vars.record_url

Scope: Global within a single call session. Variables persist across all sections and through execute calls. However, connecting to a new leg of a call will reset the vars object to an empty state.

Variable access: Variables can be accessed with or without the vars. prefix. When you reference a variable without a scope prefix (e.g., ${my_variable}), SWML first checks vars. If not found in vars, it automatically falls back to envs.

Example: Variables in JSON format

When SWML communicates with your SWML server, the following request body format is used to represent variables:

1
{
2
  "call": {
3
    "call_id": "<CALL_UUID>",
4
    "node_id": "<NODE_ID>",
5
    "segment_id": "<SEGMENT_ID>",
6
    "call_state": "created",
7
    "direction": "inbound",
8
    "type": "sip",
9
    "from": "sip:user@example.com",
10
    "to": "sip:destination@yourdomain.com",
11
    "headers": [],
12
    "sip_data": {
13
      "sip_req_user": "destination",
14
      "sip_req_uri": "destination@yourdomain.com",
15
      "sip_req_host": "yourdomain.com",
16
      "sip_from_user": "user",
17
      "sip_from_uri": "user@example.com",
18
      "sip_from_host": "example.com",
19
      "sip_to_user": "destination",
20
      "sip_to_uri": "destination@yourdomain.com",
21
      "sip_to_host": "yourdomain.com",
22
      "sip_contact_user": "user",
23
      "sip_contact_port": "5060",
24
      "sip_contact_uri": "user@192.168.1.100:5060",
25
      "sip_contact_host": "192.168.1.100",
26
      "sip_contact_params": {}
27
    },
28
    "project_id": "<YOUR PROJECT ID>",
29
    "space_id": "<YOUR SPACE ID>"
30
  },
31
  "vars": {
32
    "user_selection": "1"
33
  },
34
  "envs": {
35
    "api_key": "<YOUR_API_KEY>",
36
    "webhook_url": "https://example.com/webhook"
37
  },
38
  "params": {
39
    "department": "sales"
40
  }
41
}

Variables in serverless and server-based SWML

All SWML variables (call, params, vars, envs) are available in both serverless (Dashboard-hosted) and server-based (external URL) deployments.

Serverless (dashboard-hosted) scripts

When SWML is executed directly from the SignalWire Dashboard, access variables using the ${} syntax:

1
version: 1.0.0
2
sections:
3
  main:
4
    - set:
5
        department: sales
6
    - play:
7
        url: 'say: You are calling from ${call.from}'
8
    - play:
9
        url: 'say: Department is ${vars.department}'

Server-based (external URL) scripts

When SWML is served from your web server, SignalWire sends the current variable state as JSON in the POST request body (see the JSON format example above).

You have two options for working with these variables in your SWML response:

Option 1: Use variable expansion syntax

Use ${} syntax in your returned SWML, and SignalWire will substitute the values at runtime:

1
version: 1.0.0
2
sections:
3
  main:
4
    - play:
5
        url: 'say: Welcome to ${params.department}'
6
    - play:
7
        url: 'say: Calling from ${call.from}'

Option 2: Extract and insert values server-side

Extract variables from the request body in your server code and insert them directly into the SWML response:

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

5
  // Extract values from the request
6
  const department = params.department || 'support';
7
  const callerNumber = call.from;
8
  const apiKey = envs.api_key;
9

10
  // Build SWML with values inserted directly
11
  const swml = {
12
    version: '1.0.0',
13
    sections: {
14
      main: [
15
        {
16
          play: {
17
            url: `say: Welcome to ${department}`
18
          }
19
        },
20
        {
21
          play: {
22
            url: `say: Calling from ${callerNumber}`
23
          }
24
        }
25
      ]
26
    }
27
  };
28

29
  res.json(swml);
30
});

Both approaches produce the same result. Use variable expansion (${}) for simpler cases, or extract values server-side when you need to perform logic or transformations on the data.

See the Deployment Guide for complete server setup instructions.

Accessing variable data

Variables can contain different types of data - simple values, nested objects, or arrays. Use dot notation (.) for object properties, bracket notation ([]) for array elements, or combine both for complex data structures.

Simple values

Access variables directly by name:

1
version: 1.0.0
2
sections:
3
  main:
4
    - set:
5
        name: Alice
6
        age: 30
7
    - play:
8
        url: 'say: Hello ${name}, you are ${age} years old'

Nested objects

Access nested properties using dot notation:

1
version: 1.0.0
2
sections:
3
  main:
4
    - set:
5
        user:
6
          name: Alice
7
          address:
8
            city: Seattle
9
            state: WA
10
    - play:
11
        url: 'say: ${user.name} lives in ${user.address.city}, ${user.address.state}'

Arrays

Access array elements using bracket notation with zero-based indexing:

1
version: 1.0.0
2
sections:
3
  main:
4
    - set:
5
        departments:
6
          - Sales
7
          - Support
8
          - Engineering
9
    - play:
10
        url: 'say: First department is ${departments[0]}'
11
    - play:
12
        url: 'say: Second department is ${departments[1]}'

Arrays of objects

Combine bracket and dot notation to access properties in array elements:

1
version: 1.0.0
2
sections:
3
  main:
4
    - set:
5
        employees:
6
          - name: Alice
7
            role: Engineer
8
          - name: Bob
9
            role: Manager
10
    - play:
11
        url: 'say: ${employees[0].name} is an ${employees[0].role}'
12
    - play:
13
        url: 'say: ${employees[1].name} is a ${employees[1].role}'