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.
Parameters
The execute
statement expects either a destination string, or a execute 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. Theparams
object is passed, along with the variables and theCall
object.
Name | Type | Description |
---|---|---|
execute Required | object | The execute params object. |
execute params
Name | Type | Description |
---|---|---|
dest Required | string | Specifies what to execute. The value can be one of:
|
params Optional | object | Named parameters to send to section or URL |
on_return Optional | object | SWML to execute after return |
Examples
Executing a subroutine
- YAML
- 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}'
{
"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
- 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)}'
{
"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
- JSON
version: 1.0.0
sections:
main:
- answer: {}
- execute:
dest: 'https://<YOUR_NGROK_UUID>.ngrok-free.app'
params:
some_info: 12345
{
"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)
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
.