transfer

Transfer the execution of the script to a new URL. Unlike execute, transfer doesn't return control back to the calling document.

Parameters

The destination string can be one of:

• "section_name" - section in the current document to execute. (For example: execute: main)
• "relay:<relay application>" - relay application to notify (currently not implemented)
• "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	Description
dest or transfer_params	string or transfer params object	Either the dest string an an implicit parameter, or the transfer_params object described below

transfer params

Name	Type	Required?	Description
dest	string	Required	Specifies where to transfer to. Required. The value can be one of: "<label>" - section in document to jump to "relay:<relay application>" - relay application to notify (currently not implemented) "https://<URL>" - URL to fetch next document from. Sends HTTP POST
params	object		Named parameters to send to a section, URL, or application. Optional. Default is not set.

Examples

Named parameter

YAML

version: 1.0.0
sections:
  main:
    - transfer:
        dest: "https://example.com/next"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "transfer": {
          "dest": "https://example.com/next"
        }
      }
    ]
  }
}

Named parameter with sub-parameters

YAML

version: 1.0.0
sections:
  main:
    - transfer:
        - dest: "https://example.com/next"
        - params:
            - foo: "bar"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "transfer": [
          {
            "dest": "https://example.com/next"
          },
          {
            "params": [
              {
                "foo": "bar"
              }
            ]
          }
        ]
      }
    ]
  }
}

Implicit first parameter

YAML

version: 1.0.0
sections:
  main:
    - transfer: "https://example.com/next"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "transfer": "https://example.com/next"
      }
    ]
  }
}

Transfer to a SWML script hosted on a server

YAML

version: 1.0.0
sections:
  main:
    - prompt: "say: Press 1 to be transfered to the Sales department, 2 for marketing
        department or anything else to listen to some music."
    - switch:
        variable: prompt_value
        case:
          "1":
            - transfer:
                dest: https://<YOUR_NGROK_UUID>.ngrok-free.app
                params:
                  where: sales
          "2":
            - transfer:
                dest: https://<YOUR_NGROK_UUID>.ngrok-free.app
                params:
                  where: marketing
    - play: https://cdn.signalwire.com/swml/April_Kisses.mp3

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "prompt": "say: Press 1 to be transfered to the Sales department, 2 for marketing department or anything else to listen to some music."
      },
      {
        "switch": {
          "variable": "prompt_value",
          "case": {
            "1": [
              {
                "transfer": {
                  "dest": "https://<YOUR_NGROK_UUID>.ngrok-free.app",
                  "params": {
                    "where": "sales"
                  }
                }
              }
            ],
            "2": [
              {
                "transfer": {
                  "dest": "https://<YOUR_NGROK_UUID>.ngrok-free.app",
                  "params": {
                    "where": "marketing"
                  }
                }
              }
            ]
          }
        }
      },
      {
        "play": "https://cdn.signalwire.com/swml/April_Kisses.mp3"
      }
    ]
  }
}

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: Welcome to the {} department."

'''.format(content['params']['where'])

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 payload in the following format:

{
  "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",
    "prompt_result": "match_digits",
    "prompt_value_raw": "2",
    "prompt_value": "2"
  },
  "params": { "where": "marketing" }
}

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