# HTTP Request

The HTTP Request component reaches out to a web server while a call is in progress, letting your call flow trade data with a third-party service. HTTP (HyperText Transfer Protocol) is the same protocol web browsers use to talk to websites. Whatever the server sends back is captured in variables, so later components can act on the response, feeding it into another component or testing it in a condition to decide where the call goes next.

:::tip[Why you would use this]
Reach for HTTP Request whenever the call flow needs to know something only an outside system holds. Common examples: look up a caller in a CRM (Customer Relationship Management) system to greet a VIP differently, check whether an account is past due before routing to billing, or notify an external workflow that a call has arrived.
:::

## What it does

The component can issue any of the standard HTTP methods. In everyday use, GET reads information from the server and POST or PUT send information to it. The remaining methods cover less common cases.

- GET
- HEAD
- OPTIONS
- POST
- PUT
- TRACE
- DELETE

It also understands a wide range of content types, so you can match whatever the target service expects. The content type tells the server how to interpret the body you send:

- `application/javascript`
- `application/json`
- `application/x-www-form-urlencoded`
- `application/pdf`
- `application/xml`
- `application/zip`
- `multipart/form-data`
- `text/css`
- `text/html`
- `text/plain`
- `image/png`
- `image/jpeg`
- `image/gif`

## Configure the component

1. Drag the **HTTP Request** component onto your call flow, then click it to open its settings.

   ![The HTTP Request block placed on the call flow canvas](/images/pbx/http-request-component-cfd.png)

2. Fill in the request details.

   :::caution[This makes your phone system call an outside server]
   Point the request only at addresses you trust, and prefer an `https://` address so the traffic is encrypted. The request can carry caller details such as the phone number, so treat the target endpoint the same way you would any system that handles customer data.
   :::

   | Setting | Description |
   |---------|-------------|
   | **URI** | The address the request is sent to (URI stands for Uniform Resource Identifier, essentially a web address). Type a fixed URI, or click the **fx** (function) button to build it from an expression. For example, `FX_CONCATENATE("https://crm.example.com/check-caller?callernum=",$Session.ani)` sends the request to a CRM so it can look up the caller's number and return the caller type. Here `$Session.ani` is the caller's own phone number (ANI, Automatic Number Identification). |
   | **Request Type** | The HTTP method to use: GET, HEAD, OPTIONS, POST, PUT, TRACE, or DELETE. |
   | **Content Type** | The content type of the request, chosen from the supported list above. |
   | **Query Parameter** | Click **Add** for each parameter you want to append to the URL. Enter a fixed value, or click the **fx** button to supply an expression. For example, a key of `FX_CONCATENATE("call_to_", $Session.did)` paired with a value of `$Session.ani` passes both the dialed number and the caller's number, so the CRM can tell which service line was called. Here `$Session.did` is the number the caller dialed to reach you (DID, Direct Inward Dialing). |
   | **Content** | The request body. Enter plain text, or embed variables and functions. To insert a variable, type `$`, pick the variable, and wrap it in single quotes, for example, `'$Session.ani'`. To insert a function, type `FX`, choose and configure it, then wrap it in single quotes, for example, `'FX_CONCATENATE("test",$Session.ani)'`. |
   | **Timeout(s)** | How many seconds to wait for the request to finish. |
   | **Timeout Destination** | Optional. Turn this on to route the call somewhere specific when the request times out. After you finish configuring the component, add the follow-on components to its **Default Destination** and **Timeout Destination** branches. |
   | **Header** | Click **Add** for each HTTP header the request should carry. Enter a fixed value, or click the **fx** button for an expression. For example, a header named `X-Caller-ID` with a value of `$Session.ani` lets the CRM read the caller's number straight from the request header and match it to an existing contact. |

   :::note
   - Keep query parameters and headers to no more than 30 each.
   - For the full list of supported variables and functions, see [Variables and Functions in Cloud Voice Expression](/pbx/call-flow-designer-guide/constants-and-variables-in-cloud-voice-cfd-expression/).
   :::

   :::caution[The caller waits while the request runs]
   The call is held on the line until the server answers or the timeout you set is reached, so keep **Timeout(s)** short (a few seconds) to avoid leaving callers in silence if the server is slow or unreachable. If you enable **Timeout Destination**, you must connect components to both the **Default Destination** and **Timeout Destination** branches, otherwise a timed-out call has nowhere to go.
   :::

3. Click **Confirm** in the bottom-right corner.

## Variables

Each time the component runs, it stores the response in variables. You can read these from any expression-aware component, **Condition**, for instance, to retrieve the result and branch on it.

:::note
Because a call flow can hold several HTTP Request components, each one is numbered in the order you add it (HTTP Request 1, HTTP Request 2, and so on). Include the matching index in the variable name so you read the result from the right component.
:::

| Variable | Type | Description | Example |
|----------|------|-------------|---------|
| `$HttpRequest{index}.responseContent` | String | The body returned in the HTTP response. | `{"authenticated": true, "user": "10000"}` |
| `$HttpRequest{index}.responseStatusCode` | String | The HTTP status code the request returned. | `"200"` |

:::caution[Compare status codes against the bare number]
When you test the status code with a function, compare against the numeric code only, `200`, not `200 OK`, with no surrounding text. If any extra text is included, the comparison will not match and the branch will never fire.
:::

## What it can connect to

An HTTP Request component leads to **one or two** downstream components, two when **Timeout Destination** is enabled, so you can handle the timeout branch on its own. Any of the following can follow it:

| Component | Purpose |
|-----------|---------|
| [Prompt](/pbx/call-flow-designer-guide/prompt/) | Play an audio file or a text-to-speech message to the caller. |
| [Business Hours](/pbx/call-flow-designer-guide/business-hours/) | Route the call to different destinations depending on the time of day. |
| [Menu](/pbx/call-flow-designer-guide/menu/) | Offer callers a set of options and route them by the DTMF key they press (DTMF, Dual-Tone Multi-Frequency, is the tone a phone sends when a key is pressed). |
| [User Input](/pbx/call-flow-designer-guide/user-input/) | Collect DTMF digits from the caller, usually paired with **Condition** to act on what was entered. |
| [Language](/pbx/call-flow-designer-guide/language/) | Change the system prompt language for the rest of the flow. |
| [Record](/pbx/call-flow-designer-guide/record/) | Start recording once the caller connects to another party, with optional notification prompts, or turn recording off for a call that would otherwise be recorded. |
| [Dial by Number](/pbx/call-flow-designer-guide/dial-by-number/) | Let callers dial a number directly to reach their destination. |
| [Dial by Name](/pbx/call-flow-designer-guide/dial-by-name/) | An end component that lets callers reach a user by typing the first three letters of their name. |
| [Transfer](/pbx/call-flow-designer-guide/transfer/) | An end component that sends the caller to a chosen destination, with optional prompts announcing the transfer. |
| [Hang Up Call](/pbx/call-flow-designer-guide/hang-up-call/) | An end component that disconnects the call. |
| [Condition](/pbx/call-flow-designer-guide/condition/) | Route the call based on logical expressions. |
| [Loop](/pbx/call-flow-designer-guide/loop/) | Repeat a group of components a set number of times or until a condition is met. |
| Internal Data Ops | Read from and write to the Cloud Voice system's own database. See [Get Extension Presence Status](/pbx/call-flow-designer-guide/get-extension-presence-status/), [Set Extension Presence Status](/pbx/call-flow-designer-guide/set-extension-presence-status/), [Get Queue Agent](/pbx/call-flow-designer-guide/get-queue-agent/), [Get Queue Info](/pbx/call-flow-designer-guide/get-queue-info/), [Get Agent Status](/pbx/call-flow-designer-guide/get-agent-status/), [Set Agent Status](/pbx/call-flow-designer-guide/set-agent-status/), [Get System Info](/pbx/call-flow-designer-guide/get-system-info/), [Get System Capacity](/pbx/call-flow-designer-guide/get-system-capacity/), [Get Extension Info](/pbx/call-flow-designer-guide/get-extension-info/), and [Get Company Contact Info](/pbx/call-flow-designer-guide/get-company-contact-info/). |
| [Email Sender](/pbx/call-flow-designer-guide/email-sender/) | Send an email for real-time notifications, alerts, or user-specific information. |
| [Database Access](/pbx/call-flow-designer-guide/database-access/) | Run a SQL (Structured Query Language) query or update against a database during the call flow. |
| [HTTP Request](/pbx/call-flow-designer-guide/http-request/) | Send another HTTP request to an external server to exchange data with a third-party service. |