SWML Variables

Complete reference for variables and scopes in SWML

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.

Variable syntax

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

YAML

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

JSON

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

Variables list

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

call

object

Information about the current call. Contains the following properties.

Scope: Call-specific and read-only. Each call leg (A-leg, B-leg) has its own unique call object with different call_id, from, to, etc. When connecting to a new leg, the call object is re-initialized with the new leg's data.

call.call_id

string

A unique identifier for the call.

call.call_state

string

The current state of the call.

call.direction

string

The direction of this call. Possible values: inbound, outbound

call.from

string

The number/URI that initiated this call.

call.headers

object[]

The headers associated with this call.

call.headers[].name

string

The name of the header.

call.headers[].value

string

The value of the header.

call.node_id

string

A unique identifier for the node handling the call.

call.project_id

string

The Project ID this call belongs to.

call.segment_id

string

A unique identifier for the current call segment.

call.sip_data

object

SIP-specific data for SIP calls. Only present when call.type is sip. Contains detailed SIP header information.

call.space_id

string

The Space ID this call belongs to.

call.to

string

The number/URI of the destination of this call.

call.type

string

The type of call. Possible values: sip, phone, webrtc

sip_data.sip_contact_host

string

The host portion of the SIP Contact header.

sip_data.sip_contact_params

object

Additional parameters from the SIP Contact header.

sip_data.sip_contact_port

string

The port from the SIP Contact header.

sip_data.sip_contact_uri

string

The full URI from the SIP Contact header.

sip_data.sip_contact_user

string

The user portion of the SIP Contact header.

sip_data.sip_from_host

string

The host portion of the SIP From header.

sip_data.sip_from_uri

string

The full URI from the SIP From header.

sip_data.sip_from_user

string

The user portion of the SIP From header.

sip_data.sip_req_host

string

The host portion of the SIP request URI.

sip_data.sip_req_uri

string

The full SIP request URI.

sip_data.sip_req_user

string

The user portion of the SIP request URI.

sip_data.sip_to_host

string

The host portion of the SIP To header.

sip_data.sip_to_uri

string

The full URI from the SIP To header.

sip_data.sip_to_user

string

The user portion of the SIP To header.

envs

object

Environment variables configured at the account or project level in your SignalWire configuration. These provide access to account-wide settings and configuration values.

Coming soon!

The envs object is included in POST request bodies to external servers, but the ability to set environment variables in the SignalWire Dashboard is not yet available in production. This feature is coming soon.

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

params

object

Parameters that are user-defined and set by the calling the execute or transfer method.

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

vars

object

Script variables that can be set, modified, and accessed throughout your SWML script.

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:

{
  "call": {
    "call_id": "<CALL_UUID>",
    "node_id": "<NODE_ID>",
    "segment_id": "<SEGMENT_ID>",
    "call_state": "created",
    "direction": "inbound",
    "type": "sip",
    "from": "sip:user@example.com",
    "to": "sip:destination@yourdomain.com",
    "headers": [],
    "sip_data": {
      "sip_req_user": "destination",
      "sip_req_uri": "destination@yourdomain.com",
      "sip_req_host": "yourdomain.com",
      "sip_from_user": "user",
      "sip_from_uri": "user@example.com",
      "sip_from_host": "example.com",
      "sip_to_user": "destination",
      "sip_to_uri": "destination@yourdomain.com",
      "sip_to_host": "yourdomain.com",
      "sip_contact_user": "user",
      "sip_contact_port": "5060",
      "sip_contact_uri": "user@192.168.1.100:5060",
      "sip_contact_host": "192.168.1.100",
      "sip_contact_params": {}
    },
    "project_id": "<YOUR PROJECT ID>",
    "space_id": "<YOUR SPACE ID>"
  },
  "vars": {
    "user_selection": "1"
  },
  "envs": {
    "api_key": "<YOUR_API_KEY>",
    "webhook_url": "https://example.com/webhook"
  },
  "params": {
    "department": "sales"
  }
}

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:

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

{
  "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) 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:

YAML

version: 1.0.0
sections:
  main:
    - play:
        url: 'say: Welcome to ${params.department}'
    - play:
        url: 'say: Calling from ${call.from}'

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "play": {
          "url": "say: Welcome to ${params.department}"
        }
      },
      {
        "play": {
          "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:

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

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

  // Build SWML with values inserted directly
  const swml = {
    version: '1.0.0',
    sections: {
      main: [
        {
          play: {
            url: `say: Welcome to ${department}`
          }
        },
        {
          play: {
            url: `say: Calling from ${callerNumber}`
          }
        }
      ]
    }
  };

  res.json(swml);
});

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:

YAML

version: 1.0.0
sections:
  main:
    - set:
        name: Alice
        age: 30
    - play:
        url: 'say: Hello ${name}, you are ${age} years old'

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "set": {
          "name": "Alice",
          "age": 30
        }
      },
      {
        "play": {
          "url": "say: Hello ${name}, you are ${age} years old"
        }
      }
    ]
  }
}

Nested objects

Access nested properties using dot notation:

YAML

version: 1.0.0
sections:
  main:
    - set:
        user:
          name: Alice
          address:
            city: Seattle
            state: WA
    - play:
        url: 'say: ${user.name} lives in ${user.address.city}, ${user.address.state}'

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "set": {
          "user": {
            "name": "Alice",
            "address": {
              "city": "Seattle",
              "state": "WA"
            }
          }
        }
      },
      {
        "play": {
          "url": "say: ${user.name} lives in ${user.address.city}, ${user.address.state}"
        }
      }
    ]
  }
}

Arrays

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

YAML

version: 1.0.0
sections:
  main:
    - set:
        departments:
          - Sales
          - Support
          - Engineering
    - play:
        url: 'say: First department is ${departments[0]}'
    - play:
        url: 'say: Second department is ${departments[1]}'

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "set": {
          "departments": [
            "Sales",
            "Support",
            "Engineering"
          ]
        }
      },
      {
        "play": {
          "url": "say: First department is ${departments[0]}"
        }
      },
      {
        "play": {
          "url": "say: Second department is ${departments[1]}"
        }
      }
    ]
  }
}

Arrays of objects

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

YAML

version: 1.0.0
sections:
  main:
    - set:
        employees:
          - name: Alice
            role: Engineer
          - name: Bob
            role: Manager
    - play:
        url: 'say: ${employees[0].name} is an ${employees[0].role}'
    - play:
        url: 'say: ${employees[1].name} is a ${employees[1].role}'

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "set": {
          "employees": [
            {
              "name": "Alice",
              "role": "Engineer"
            },
            {
              "name": "Bob",
              "role": "Manager"
            }
          ]
        }
      },
      {
        "play": {
          "url": "say: ${employees[0].name} is an ${employees[0].role}"
        }
      },
      {
        "play": {
          "url": "say: ${employees[1].name} is a ${employees[1].role}"
        }
      }
    ]
  }
}