Skip to navigation
Messaging

transfer

View as MarkdownOpen in Claude

Hand processing over to another section, another SWML document fetched from a URL, or an inline SWML document. This is a tail call: it does not return, and steps after transfer, including steps in calling sections, are skipped. A URL or inline destination also replaces the current document.

Properties

transfer
objectRequired

An object that accepts the following properties.

transfer.dest
stringRequired

Where to transfer. Accepts any valid destination. %{...} variable references in dest are expanded before the destination is resolved.

transfer.method
stringDefaults to POST

HTTP method for the fetch request. One of GET, POST, PUT, PATCH, or DELETE. Used only when dest is a URL.

transfer.params
objectDefaults to {}

Parameters for the transferred section or document, available there as params.*. When dest is a URL, they are also sent in the request body. They replace the current params rather than merging with them; when omitted, the target receives an empty object.

String values are expanded for %{...} variable references at every depth, including inside nested objects and arrays. Keys are not expanded. Each substitution produces a string, a reference to a path that doesn’t exist becomes an empty string, and expressions are not evaluated.

Valid destinations

transfer.dest takes one of three forms:

  • Section name — the name of a section in the current document, such as support. The section runs with the document’s current variables.
  • URL — an http or https URL that returns a messaging SWML document. SignalWire fetches it with method and sends the inbound message webhook payload described below in the request body. Authentication can be set in the URL in the format username:password@url.
  • Inline document — a complete messaging SWML document, supplied as a string that holds the document serialized as a JSON object. A YAML or JSON object nested directly under dest is not accepted, and a string that isn’t a valid JSON object is treated as a section name. Execution starts at the document’s sections.main.

Webhook payload sent to dest

When dest is a URL, SignalWire sends the inbound message webhook payload in the request body to dest, using method (POST by default):

  • message — the original inbound message that triggered this SWML document.
  • params — the values supplied to this transfer step.
  • vars — runtime variables propagated from the current document (request_result, reply_result, request_response, request_response_code, request_response_body, reply_message_id). Present on transfer-driven fetches; absent on the initial inbound fetch.
Payload
{
"message": {
"message_id": "c2d3e4f5-a6b7-8901-cdef-234567890abc",
"project_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"space_id": "d3e4f5a6-b7c8-9012-defa-345678901bcd",
"direction": "inbound",
"type": "sms",
"from": "+15551231234",
"to": "+15553214321",
"body": "Hello, I need help",
"media": [],
"segments": 1,
"timestamp": "2024-01-15T10:30:00Z"
},
"params": {}
}

Examples

Transfer to an external SWML handler

version: 1.0.0
sections:
main:
- transfer:
dest: "https://example.com/messaging-handler"
params:
reason: "escalation"

Transfer to a section with expanded params

String values inside params are expanded before the transfer, including values in nested arrays.

version: 1.0.0
sections:
main:
- transfer:
dest: support
params:
customer: "%{message.from}"
topics:
- "%{message.body}"
support:
- reply: "Thanks, %{params.customer}. An agent will reply about: %{params.topics[0]}"

Transfer to 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:
- transfer:
dest: '{"version":"1.0.0","sections":{"main":[{"reply":"Thanks, we got your message."}]}}'

Route to different handlers based on keyword

version: 1.0.0
sections:
main:
- switch:
variable: message.body
transform: lowercase_trim
case:
sales:
- transfer:
dest: "https://example.com/sales-handler"
params:
source: "sms"
support:
- transfer:
dest: "https://example.com/support-handler"
params:
source: "sms"
default:
- reply:
body: "Reply SALES or SUPPORT to be routed to the right team."