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 — they set request_result but do not stop execution, so the document can branch on the outcome without failing the inbound message.

Properties

objectRequired

An object containing the following properties.

request.url

stringRequired

Endpoint to call. Must be a publicly reachable URL.

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. Objects are JSON-encoded automatically.

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 JSON response into request_response.* variables.

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.

request_result

string

Outcome of the request. Always set. One of success (request completed with a 2xx response), failed (network error or non-2xx response), timeout (request exceeded timeout, or the 5-second platform maximum), or limit_exceeded (the document already used the maximum of 10 request calls).

request_response_code

integer

HTTP status code from the response. Set when the request was actually sent. Absent when request_result is limit_exceeded.

request_response_body

string

Raw response body, truncated to 64 KB. Set when the response had a body. Absent when request_result is limit_exceeded.

request_response.<field>

any

Variables saved from the parsed JSON response when save_variables is true. 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:

1 { "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

1 version: 1.0.0
2 sections:
3   main:
4     - request:
5         url: "https://api.example.com/lookup"
6         method: POST
7         body:
8           phone: "%{message.from}"
9         save_variables: true
10         timeout: 3
11     - reply:
12         body: "Hi %{request_response.name}, thanks for reaching out!"

Branch on request_result

1 version: 1.0.0
2 sections:
3   main:
4     - request:
5         url: "https://api.example.com/lookup"
6         save_variables: true
7     - switch:
8         variable: request_result
9         case:
10           success:
11             - reply:
12                 body: "Found you in our system."
13           failed:
14             - reply:
15                 body: "Sorry, we couldn't reach the lookup service."
16           timeout:
17             - reply:
18                 body: "Lookup timed out — please try again later."
19         default:
20           - reply:
21               body: "Unable to look up your account."