execute

Execute a specified section or URL as a subroutine, and upon completion, return to the current document. Use the return statement to pass any return values or objects back to the current document.

Name	Type	Default	Description
executeRequired	object	-	An object that accepts the execute params.

execute Parameters

Name	Type	Default	Description
destRequired	string	-	Accepts any valid destination
paramsOptional	object	-	Named parameters to send to section or URL
on_returnOptional	object	-	SWML to execute after return
resultOptional	object | object[]	-	Action to take based on the result of the call. This will run once the peer leg of the call has ended. Will use the switch method when the return_value is a object, and will use the cond method when the return_value is an array.

Valid Destinations

The destination string can be one of:

• "section_name" - section in the current document to execute. (For example: main)
• "https://example.com/sub-swml.yaml" - URL pointing to the document to execute. An HTTP POST request will be sent to the URL. The params object is passed, along with the variables and the Call object. Authentication can also be set in the url in the format of username:password@url.

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:
        url: '${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": {
          "url": "${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:
                      url: 'say: Math works!'
                '23':
                  - play:
                      url: 'say: Wrong'
              default:
                - play:
                    url: 'say: Bad robot! ${return_value}'
  my_arithmetic:
    - 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": {
                        "url": "say: Math works!"
                      }
                    }
                  ],
                  "23": [
                    {
                      "play": {
                        "url": "say: Wrong"
                      }
                    }
                  ]
                },
                "default": [
                  {
                    "play": {
                      "url": "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:
        url: "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:
        url: "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.