SignalWire Docs

Appearance

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:

YAMLJSON

version: 1.0.0
sections:
  main:
    - play:
        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.

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:

YAMLJSON

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:

YAMLJSON

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:

YAMLJSON

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:

YAMLJSON

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:

YAMLJSON

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:

YAMLJSON

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}'

SignalWire Developer Documentation

Internal SOP Reference