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.

Properties

objectRequired

An object that accepts the following properties.

execute.dest

stringRequired

Accepts any valid destination

execute.params

object

Named parameters to send to section or URL. After variable expansion, params can nest objects and arrays at most 63 levels deep, counting the params object itself. If params is nested deeper, the section or URL isn’t executed, a relay_script_nested_too_deep warning is reported, and the methods after execute in the current section don’t run.

execute.meta

object

User-defined metadata. This data is ignored by SignalWire and can be used for your own tracking purposes.

execute.on_return

object[]

Array of SWML methods to execute when the executed section or URL returns.

execute.result

object | object[]

Instructions to run based on the value returned by the executed section or URL. result is processed after the section or URL returns and before on_return, and only when the section or URL set a return_value (for example, with return).

An object-shaped result is handled like the switch method: its case keys are matched against return_value. An array-shaped result is handled like the cond method: a list of conditions checked in order.

Valid Destinations

The destination string can be one of:

"section_name" - section in the current document to execute. (For example: main)
A URL (http or https) - 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.
An inline SWML document (as a JSON string) - SWML document provided directly as a JSON string.

Examples

Executing a subroutine

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

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 script hosted on a server

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

JavaScript/Express

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)

This server (running on localhost) can be made accessible to the wider web (and thus this SWML script) using forwarding tools like ngrok. Visit ngrok.com 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 Calling overview. 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.