Skip to navigation
Messaging

execute

View as MarkdownOpen in Claude

Run a section, a SWML document fetched from a URL, or an inline SWML document as a subroutine. Execution continues in the called section or document, then returns to the caller when it completes (via return or by reaching the end). A called document starts at its sections.main.

Properties

execute
string | objectRequired

Either a destination string (shorthand) or an object that accepts the properties below. The shorthand calls the destination with empty params, and %{...} references in it are not expanded. Use the object form to build the destination or pass parameters from variables.

execute.dest
stringRequired

Where to execute. Accepts any valid destination.

execute.params
object

Parameters accessible as params.* in the called section or document. Replaces (does not merge with) any outer params from the caller.

Valid destinations

The destination, in either the shorthand or execute.dest, takes one of three forms:

  • Section name — the name of a section in the current document, such as greet.
  • URL — an http or https URL that returns a messaging SWML document. SignalWire fetches it with a POST request carrying the inbound message webhook payload, with params set to the values supplied here and vars set to the caller’s current variables.
  • Inline document — a complete messaging SWML document, supplied as a string that holds the document serialized as a JSON object. A string that isn’t a valid JSON object is treated as a section name.

A called section runs with the caller’s variables, with params replaced. A called URL or inline document starts fresh: it sees the inbound message and the params supplied here, but not the caller’s other variables, such as request_result. Pass any values the document needs in params.

Variables

After the called section or document completes, execute exposes the following variable in the caller’s context. Variables that the subroutine itself set via reply or request — reply_result, reply_message_id, request_result, request_response, request_response_code, request_response_body — are also propagated back to the caller automatically; see those methods for details.

return_value
any

The value supplied to return inside the called section or document. When the subroutine explicitly returns, its value is assigned to the caller’s return_value; return: null assigns null. Completing without return does not assign a new value or clear an existing one, so a value from an earlier subroutine remains.

Examples

Calling a subroutine

version: 1.0.0
sections:
main:
- execute:
dest: greet
params:
name: "%{message.from}"
- reply:
body: "%{return_value}"
greet:
- return: "Hello, %{params.name}!"

Branch on the subroutine return value

version: 1.0.0
sections:
main:
- execute:
dest: classify
params:
body: "%{message.body}"
- switch:
variable: return_value
case:
opt_out:
- reply:
body: "You've been unsubscribed."
help:
- reply:
body: "Reply STOP to unsubscribe."
default:
- reply:
body: "Thanks for your message!"
classify:
- switch:
variable: params.body
transform: lowercase_trim
case:
stop:
- return: "opt_out"
help:
- return: "help"
default:
- return: "other"

Shorthand call to a section

version: 1.0.0
sections:
main:
- execute: greet
- reply: "Reply HELP for options."
greet:
- reply: "Thanks for texting us."

Execute a document from a URL

version: 1.0.0
sections:
main:
- execute:
dest: "https://example.com/swml/classify"
params:
body: "%{message.body}"
- reply: "Your request was filed as: %{return_value}"

Execute an inline document

The inline document is a JSON string, so its quotes are escaped in JSON and the whole value is quoted in YAML.

version: 1.0.0
sections:
main:
- execute:
dest: '{"version":"1.0.0","sections":{"main":[{"return":"general"}]}}'
- reply: "Your request was filed as: %{return_value}"