Deploy SWML from web servers

SWML scripts can be served in multiple ways beyond the SignalWire Dashboard. This guide covers serving SWML from web servers and RELAY applications.

From a web server

In the phone number settings, when you check the “Use External URL for SWML Script handler?” option, you can set a Web URL that will serve the SWML script. Every time a call comes in (or some other designated event occurs), SignalWire sends a POST request to the URL using the standard document-fetching webhook format. The request body contains the call object, vars, params, and envs. See the document-fetching webhook reference for the full request body structure.

Understanding the POST Request

The vars object and the params object will be empty for a new call. If you’re executing a remote SWML script using the execute or transfer methods, the vars parameter has a list of the variables declared in the script so far. And the params object has the list of parameters explicitly set by the execute or transfer methods.

You can also reference the properties of call and params objects during the script execution using the variable subtitution bracket like so:

1
version: 1.0.0
2
sections:
3
  main:
4
    - play:
5
        url: 'say:%{call.from}'

Further, consider the following SWML script:

1
version: 1.0.0
2
sections:
3
  main:
4
    - play:
5
        url: '%{params.file}'
6
    - return: 1

It references params.file in its play method. If this SWML was invoked as a response to a phone call, it would cause an error as the params object is empty. But if it was hosted on a server and called with the execute or the transfer method, the params object is passed into the SWML.

The SWML above can be invoked as follows:

1
version: 1.0.0
2
sections:
3
  main:
4
    execute:
5
      dest: https://example.com/swml.yaml
6
      params:
7
        file: https://cdn.signalwire.com/swml/audio.mp3

From a RELAY application

You can also execute SWML from a RELAY application. The following is a snippet using the RELAY SDK.

1
const { Voice } = require("@signalwire/realtime-api");
2
const script = `
3
version: 1.0.0
4
sections:
5
  main:
6
    - answer: {}
7
    - execute:
8
        dest: play_music
9
        params:
10
          to_play: 'https://cdn.signalwire.com/swml/April_Kisses.mp3'
11
  play_music:
12
    - play:
13
        url: '%{params.to_play}'
14
`;
15

16
const client = new Voice.Client({
17
  project: "<your project token>",
18
  token: "<your project API key>",
19
  topics: ["swml"],
20
});
21

22
client.on("call.received", async (call) => {
23
  try {
24
    await client.execute({
25
      method: "calling.transfer",
26
      params: {
27
        node_id: call.nodeId,
28
        call_id: call.callId,
29
        dest: script,
30
      },
31
    });
32
  } catch (error) {}
33
});

In this snippet, we are registering an event for every time a call is received to any phone number in your project with the topic “swml”. You can set the topics a number is subscribed to from the phone number settings page in the SignalWire Dashboard. Every time a call is received, the SWML script is executed using the client.execute method.

Next steps

• Variables and Expressions: Complete reference for SWML variables and the Call Object

• Handle incoming calls from code: Complete guide to serving SWML from web servers

• Calling SWML reference: Methods available for voice calls

• Messaging SWML reference: Methods available for inbound SMS and MMS

• Getting started with SWML: Learn the fundamentals