request

Make an HTTP request to an external URL. The response can optionally be parsed and stored as variables for use in subsequent steps.

Request failures are soft — a timeout, a connection failure, or an unsuccessful HTTP response sets request_result but does not stop execution, so the document can branch on the outcome without failing the inbound message.

The exception is a missing URL. Omitting url, or a url that expands to an empty value, is a fatal swml_request_url_required error (“Request URL is required.”), and later steps don’t run. A call past the 10-request limit is skipped before url is checked.

Properties

objectRequired

An object containing the following properties.

request.url

stringRequired

Endpoint to call. Must be a publicly reachable URL. A missing or empty url stops execution with an error instead of setting request_result.

request.method

stringDefaults to POST

HTTP method. One of GET, POST, PUT, PATCH, or DELETE.

request.headers

object

HTTP headers to include with the request, as a map of header name to value. Each value must be a string.

request.body

string | object

Request body, always sent JSON-encoded. An object is sent as a JSON object. A string is sent as a JSON string value, with quotes and escaping, not as raw text: hello is sent as "hello".

request.timeout

numberDefaults to 5.0

Timeout in seconds. Clamped to a maximum of 5.0.

request.save_variables

booleanDefaults to false

If true, parse the response into request_response.* variables. Fields are saved when the URL returns a 2xx response whose body is a JSON object; nothing is saved from 4xx or 5xx responses.

Variables

request writes these variables into the script context after the HTTP call completes (or is skipped). Read them with the %{variable} syntax in subsequent steps.

Each call updates request_result. The response variables are updated only when a response provides them, and nothing clears them: after a timeout, a connection failure, or a skipped call they can still hold values from an earlier request, and request_response keeps earlier fields whenever a call doesn’t save new ones. Check request_result before using them.

request_result

string

Outcome of the request, set when the request completes, times out, can’t connect, or is skipped by the request limit. One of success (request completed with a 2xx response), failed (the URL returned a response outside the 2xx range), timeout (no response within timeout or the 5-second platform maximum, or the connection to the URL failed), or limit_exceeded (the document already used the maximum of 10 request calls).

request_response_code

string

HTTP status code from the response, as a string such as "200". Updated when a response is received, whether or not it is a 2xx.

request_response_body

string

Response body as a stored string, updated when a response is received. It is truncated to its first 65,536 characters after the response is received; this limits the stored value, not the download. Responses with a JSON content type are stored as re-serialized JSON, so formatting can differ from what the server sent.

request_response.<field>

any

Variables saved from the parsed response when save_variables is true and the URL returns a 2xx response whose body is a JSON object. Nothing is saved from a 4xx or 5xx response, and a successful response whose body isn’t valid JSON sets request_result to success without saving fields. Each top-level key of the JSON body becomes a request_response.<key> path, with dotted paths into nested objects.

For example, if the server responds with:

{ "status": "created", "time": "2 seconds ago", "number": { "home": "n/a" } }

the variables request_response.status, request_response.time, and request_response.number.home are set.

Examples

Look up the inbound sender and reply with the result

version: 1.0.0
sections:
  main:
    - request:
        url: "https://api.example.com/lookup"
        method: POST
        body:
          phone: "%{message.from}"
        save_variables: true
        timeout: 3
    - reply:
        body: "Hi %{request_response.name}, thanks for reaching out!"

Branch on request_result

version: 1.0.0
sections:
  main:
    - request:
        url: "https://api.example.com/lookup"
        save_variables: true
    - switch:
        variable: request_result
        case:
          success:
            - reply:
                body: "Found you in our system."
          failed:
            - reply:
                body: "Sorry, we couldn't reach the lookup service."
          timeout:
            - reply:
                body: "Lookup timed out — please try again later."
        default:
          - reply:
              body: "Unable to look up your account."