> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# request

> Make an HTTP request to an external URL during inbound message handling.

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**

An object containing the following properties.

Endpoint to call. Must be a publicly reachable URL.

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

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

Request body. Objects are JSON-encoded automatically.

Timeout in seconds. Clamped to a maximum of `5.0`.

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.

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).

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

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

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:

```json
{ "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

```yaml
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!"
```

```json
{
  "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

```yaml
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."
```

```json
{
  "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."
              }
            }
          ]
        }
      }
    ]
  }
}
```