Expressions

Expressions allow you to use JavaScript within SWML variables to transform data, perform calculations, and implement logic. Instead of static values, you can dynamically construct values based on call data, user input, and calculations.

For information about variable scopes and basic access patterns, see the Variables Reference. For template transformation functions, see the Template Functions Reference.

What are expressions?

Expressions use the ${...} syntax and support JavaScript for dynamic value construction. Any JavaScript that evaluates to a value can be used inside these delimiters. Both syntaxes work identically.

SWML uses the Google V8 JavaScript engine (version 6 and later) to evaluate expressions. For detailed JavaScript feature support, refer to the V8 documentation.

1
version: 1.0.0
2
sections:
3
  main:
4
    - prompt:
5
        play: 'say: Please enter your order quantity'
6
        speech_hints:
7
          - one
8
          - two
9
          - three
10
    - set:
11
        # Set the prompt value
12
        quantity: '${prompt_value}'
13
        # Set the unit price
14
        unit_price: 5
15
        # Extract area code from caller
16
        area_code: '${call.from.substring(0, 3)}'
17
        # Calculate total with tax
18
        subtotal: '${vars.unit_price * parseInt(vars.quantity)}'
19
        tax: '${subtotal * 0.08}'
20
        total: '${subtotal + tax}'
21
        # Determine shipping message
22
        shipping_msg: '${total > 50 ? "with free shipping" : "plus shipping"}'
23
    - play:
24
        url: 'say: Your total is ${total.toFixed(2)} dollars ${shipping_msg}'

Expressions are evaluated at runtime and replaced with their computed values.

Variable access in expressions

All SWML variables are accessible within JavaScript expressions. You can reference them with or without scope prefixes:

1
- set:
2
    # With prefix (explicit)
3
    caller: '${call.from}'
4
    value: '${vars.my_variable}'
5
    setting: '${envs.api_key}'
6
    # Without prefix (automatic)
7
    formatted: '${my_variable.toUpperCase()}'

When you access a variable without a prefix, the expression engine checks scopes in this order: vars, then envs, then call. Using explicit prefixes like vars. or call. is recommended for clarity, especially when variable names might exist in multiple scopes.

When to use expressions vs. server-side logic

Expressions are evaluated at runtime within SWML and work well for simple transformations like formatting phone numbers or calculating totals. The question of when to use expressions versus server-side logic depends largely on your deployment model.

Serverless (dashboard-hosted) SWML

When hosting SWML directly in the SignalWire Dashboard, expressions become your primary tool for dynamic behavior. You can use them to transform call data like extracting area codes with ${call.from.substring(0, 3)}, perform calculations such as ${vars.unit_price * parseInt(vars.quantity)}, or make simple decisions with ternary operators.

1
version: 1.0.0
2
sections:
3
  main:
4
    - prompt:
5
        play: 'say: Please enter your order quantity'
6
        speech_hints:
7
          - one
8
          - two
9
          - three
10
    - set:
11
        # Set the prompt value
12
        quantity: '${prompt_value}'
13
        # Set the unit price
14
        unit_price: 5
15
        # Extract area code from caller
16
        area_code: '${call.from.substring(0, 3)}'
17
        # Calculate total with tax
18
        subtotal: '${vars.unit_price * parseInt(vars.quantity)}'
19
        tax: '${subtotal * 0.08}'
20
        total: '${subtotal + tax}'
21
        # Determine shipping message
22
        shipping_msg: '${total > 50 ? "with free shipping" : "plus shipping"}'
23
    - play:
24
        url: 'say: Your total is ${total.toFixed(2)} dollars ${shipping_msg}'

If you need complex logic in serverless mode, use the request method to fetch data from a server during call execution. The response data becomes available as variables that you can then manipulate with expressions.

Server-based (external URL) SWML

Serving SWML from your own web server opens up more architectural options. This is where you should handle database queries, external API calls to your business systems, and any complex business logic that requires authentication or heavy data processing.

The general pattern is to do the heavy lifting server-side before generating the SWML response, then use expressions for runtime transformations. For example, you might query your database to fetch customer information, call your internal billing service to get their account status, and insert that data directly into the SWML. Then expressions handle runtime concerns like formatting that data or calculating values based on user input collected during the call.

1
app.post('/swml-handler', async (req, res) => {
2
  const { call, params } = req.body;
3

4
  // Server-side: Query database
5
  const customer = await db.query(
6
    'SELECT * FROM customers WHERE phone = ?',
7
    [call.from]
8
  );
9

10
  // Server-side: Call internal billing API
11
  const billing = await fetch(`https://billing.yourcompany.com/api/account/${customer.id}`);
12
  const accountData = await billing.json();
13

14
  // Return SWML with data inserted
15
  const swml = {
16
    version: '1.0.0',
17
    sections: {
18
      main: [
19
        {
20
          play: {
21
            // Expression: Simple transformation at runtime
22
            url: `say: Hello ${customer.name}, your account status is ${accountData.status}`
23
          }
24
        },
25
        {
26
          set: {
27
            // Expression: Calculate with fetched data
28
            discount: '${params.base_price * 0.1}'
29
          }
30
        }
31
      ]
32
    }
33
  };
34

35
  res.json(swml);
36
});

The key principle is to use server-side logic to prepare and fetch data, then use expressions for transformations and dynamic behavior that happen during the call itself.

Common expression patterns

String operations

Transform and manipulate text using JavaScript string methods:

1
version: 1.0.0
2
sections:
3
  main:
4
    - set:
5
        first_name: 'John'
6
        last_name: 'Doe'
7
        # Extract part of a string
8
        area_code: '${call.from.substring(0, 3)}'
9
        # Change case
10
        uppercase: '${call.type.toUpperCase()}'
11
        # Combine strings
12
        full_name: '${vars.first_name + " " + vars.last_name}'
13
    - play:
14
        url: 'say: Hello ${full_name}. Your area code is ${area_code}. Call type: ${uppercase}'

Common methods: substring(), toUpperCase(), toLowerCase(), trim(), replace(), split(), join()

Arithmetic and math

Perform calculations using standard JavaScript operators and Math functions:

1
version: 1.0.0
2
sections:
3
  main:
4
    - set:
5
        # Calculate total
6
        total: '${params.price * params.quantity}'
7
        # Format currency (2 decimal places)
8
        formatted: '${total.toFixed(2)}'
9
        # Round to nearest integer
10
        rounded: '${Math.round(params.rating)}'

Use operators: +, -, *, /, % and Math functions: Math.round(), Math.ceil(), Math.floor(), Math.max(), Math.min()

Conditional logic

Use ternary operators and comparisons to make decisions:

1
version: 1.0.0
2
sections:
3
  main:
4
    - set:
5
        # Conditional greeting based on call direction
6
        greeting: '${call.direction == "inbound" ? "Welcome" : "Calling"}'
7
        # Fallback to "unknown" if call.type is null
8
        call_label: '${call.type != null ? call.type : "unknown"}'
9
        # Compound condition checking both type and direction
10
        status: '${call.type == "phone" && call.direction == "inbound" ? "valid" : "invalid"}'
11
    - play:
12
        url: 'say: ${greeting}! Your call type is ${call_label} and status is ${status}'

Use comparisons: ==, !=, >, <, >=, <= and logical operators: &&, ||

Array operations

Work with arrays using JavaScript array methods:

1
version: 1.0.0
2
  sections:
3
    main:
4
      - set:
5
          # Define the array first
6
          items:
7
            - apple
8
            - banana
9
      - set:
10
          # Get array length
11
          count: '${(items.length)}'
12
          # Join array into string
13
          list: '${vars.items.join(", ")}'
14
          # Check if array contains item
15
          has_item: '${vars.items.includes("apple")}'
16
          # Get last item
17
          last: '${vars.items[vars.items.length - 1]}'
18
      - play:
19
          url: 'say: You have ${count} items: ${list}. Last item is ${last}.'

Common methods: .length, .join(), .includes(), bracket notation for access

Type conversions

Convert between strings, numbers, and booleans:

1
version: 1.0.0
2
sections:
3
  main:
4
  - set:
5
      quantity: ${parseInt("42")}
6
      count: 100
7
      text: "${count.toString()}"
8
      is_active: "${Boolean(1)}"
9
  - play:
10
      url: 'say: The quantity is ${quantity}. The count variable is ${text}. Active is set to ${is_active}'

Use: parseInt(), parseFloat(), .toString(), Boolean()

Expression limitations

Expressions are designed for quick data transformations during calls. They work great for formatting strings, performing calculations, and making simple decisions, but they’re intentionally constrained to keep your calls running smoothly.

You can’t create custom functions with the function keyword or arrow syntax. Instead, rely on JavaScript’s built-in methods like string operations, Math functions, and array methods:

1
- set:
2
    calculator: '${function(x) { return x * 2; }}'
3

4
# Do this instead
5
- set:
6
    doubled: '${value * 2}'

Loops like for and while aren’t available, but you can use array methods for most transformation needs. Methods like .map(), .filter(), and .reduce() handle common iteration patterns:

1
# Loops aren't supported
2
- set:
3
    result: '${for(let i=0; i<10; i++) { sum += i; }}'
4

5
# Array methods work well
6
- set:
7
    sum: '${[1,2,3,4,5].reduce((a,b) => a+b, 0)}'

Simple property access like .length, .name, .value, etc. on arrays or strings require parentheses to evaluate correctly. Without them, the expression is treated as a variable lookup rather than JavaScript. Method Calls with parentheses work directly:

1
  # Property access needs parentheses
2
  - set:
3
      count: '${(items.length)}'
4
      name_length: '${(user.name.length)}'
5

6
  # Method calls work without extra syntax
7
  - set:
8
      list: '${items.join(", ")}'
9
      upper: '${name.toUpperCase()}'

Expressions execute synchronously, so you can’t use async, await, or make API calls directly. For operations that need external data, use the request method to fetch data first, then transform the results with expressions.

Keep expressions under 1,024 characters and expect them to complete within 150ms. If you’re hitting these limits, it’s usually a sign that the logic belongs in your server code rather than inline in SWML.