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

execute

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

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[]

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)
• 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

YAMLJSON

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

YAMLJSON

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

YAMLJSON

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 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.