execute

Execute a section or URL as a subroutine and return back to current document. Return values or objects are sent using the return statement.

Parameters

The execute statement expects either a destination string, or a params object with other options.

The destination string can be one of:

• "section_name" - section in the current document to execute. (For example: execute: main)
• "https://example.com/sub-swml.yaml" - URL pointing to the document to execute. A HTTP POST request will be sent to the URL. The params object is passed, along with the variables and the Call object.

Name	Type	Required?	Description
execute	destination string or execute params object	Required	Either the destination by itself, or the params object

execute params

Name	Type	Required?	Description
dest	string	Required	Specifies what to execute. The value can be one of: "<label>" - section in the current document to execute. "https://<URL>" - URL pointing to the document to execute. Sends HTTP POST.
params	object	Optional	Named parameters to send to section or URL
on_return	object	Optional	SWML to execute after return

Examples

Executing a subroutine

YAML

version: 1.0.0
sections:
  main:
    - execute:
        dest: subroutine
        params:
          to_play: https://cdn.signalwire.com/swml/April_Kisses.mp3
  subroutine:
    - answer
    - play: "%{params.to_play}"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "execute": {
          "dest": "subroutine",
          "params": {
            "to_play": "https://cdn.signalwire.com/swml/April_Kisses.mp3"
          }
        }
      }
    ],
    "subroutine": [
      "answer",
      {
        "play": "%{params.to_play}"
      }
    ]
  }
}

Executing a subroutine and branching on return

YAML

version: 1.0.0
sections:
  main:
    - answer
    - execute:
        dest: my_arithmetic
        params:
          a: 2
          b: 3
        on_return:
          - switch:
              variable: return_value
              case:
                5:
                  - play: "say: Math works!"
                23:
                  - play: "say: Wrong"
              default:
                - play: "say: Bad robot! %{return_value}"
  my_arithmetic:
    # parseInt() ensures the parameters are added as numbers, not strings
    - return: "%{parseInt(params.a) + parseInt(params.b)}"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      "answer",
      {
        "execute": {
          "dest": "my_arithmetic",
          "params": {
            "a": 2,
            "b": 3
          },
          "on_return": [
            {
              "switch": {
                "variable": "return_value",
                "case": {
                  "5": [
                    {
                      "play": "say: Math works!"
                    }
                  ],
                  "23": [
                    {
                      "play": "say: Wrong"
                    }
                  ]
                },
                "default": [
                  {
                    "play": "say: Bad robot! %{return_value}"
                  }
                ]
              }
            }
          ]
        }
      }
    ],
    "my_arithmetic": [
      {
        "return": "%{parseInt(params.a) + parseInt(params.b)}"
      }
    ]
  }
}

Execute a SWML hosted on a server

YAML

version: 1.0.0
sections:
  main:
    - answer
    - execute:
        dest: https://<YOUR_NGROK_UUID>.ngrok-free.app
        params:
          some_info: 12345

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      "answer",
      {
        "execute": {
          "dest": "https://<YOUR_NGROK_UUID>.ngrok-free.app",
          "params": {
            "some_info": 12345
          }
        }
      }
    ]
  }
}

A minimal server for this SWML script can be written as follows:

Python/Flask

from flask import Flask, request
from waitress import serve

app = Flask(__name__)

@app.route("/", methods=['POST'])
def swml():
    content = request.get_json(silent=True)
    print(content)
    return '''
version: 1.0.0
sections:
  main:
    - answer
    - play: "say: The call type is {}"

'''.format(content['call']['type'])

if __name__ == "__main__":
    serve(app, host='0.0.0.0', port=6000)

JavaScript/Express

const express = require("express");
const app = express();

app.use(express.json());

// note the POST method
app.post("/", (req, res) => {
  const data = req.body;
  console.log(data);
  res.send(`
version: 1.0.0
sections:
  main:
    - answer
    - play: "say: Welcome to the ${data.params.where} department" 
  `);
});

const port = 6000;
app.listen(port);

This server (running on localhost) can be made accessible to the wider web (and thus this SWML script) using forwarding tools like ngrok. You can follow our Testing webhooks with ngrok guide to learn how.

The server will be sent the following payload:

{
  "call": {
    "call_id": "<call_id>",
    "node_id": "<node_id>",
    "segment_id": "<segment_id>",
    "call_state": "answered",
    "direction": "inbound",
    "type": "phone",
    "from": "<address>",
    "to": "<address>",
    "from_number": "<address>",
    "to_number": "<address>",
    "headers": [],
    "project_id": "<your project UUID>",
    "space_id": "<your space UUID>"
  },
  "vars": {
    "answer_result": "success"
  },
  "params": {
    "some_info": "12345"
  }
}

The call object is described in detail in the introduction. All variables created within the SWML document are passed inside vars, and the params object contains the parameters defined in the params parameter of execute.