HTTP Request

Prev Next

Who should read this article: Administrators

The HTTP Request node allows you to send HTTP requests and receive data in JSON format, then process the data in the flow. It enables you to integrate external data into Voiso contact center interactions as custom variables.

Introduction

Use the HTTP Request node to send either a GET or a POST request to a web service.

Tip

GET requests are used to ask for data from a specified resource. They are typically used to retrieve information without changing any data on the server.

POST requests are used to send data to a server to create or update a resource. They are commonly used for form submissions, uploading files, and any operations that modify data on the server.

You can chain HTTP requests together. Use the request response to retrieve data from an endpoint and pass the data as a custom variable to the next node, such as another HTTP Request node or a Send Message node.

Connections

The HTTP Request node supports unlimited input connections and up to 2 output connections.

Important

The HTTP Request node requires at least one input connection and one output connection from either the Done or Error connection.

Use Case: Self-service contact center

You can use the HTTP Request node to build a self-service IVR for your contact center. For example, you can use a GET request to obtain various data from one or more web services, then pass the data as variables to the Send Message node to create an SMS or WhatsApp message and send it to the caller.

Use Case: Third-party system notification

The HTTP Request node can be used to collect caller information, such as the ANI (Caller ID) at the start of a flow and, using the POST method, send it to a third-party application, such as a CRM, which can then screen pop the contact's record.

Use Case: Website authorization

While a contact is browsing your website, you can present them with a phone number to call to verify their identity. When the call enters the flow, you can obtain the ANI and compare it with a phone number stored in your contact list for the person.

Using the HTTP Request node

To add an HTTP Request node to your interaction flow, click the HTTP Request icon:

Flow Builder HTTP Request Node

The HTTP Request node allows an unlimited number of input connections and up to two output connections.

Flow Builder HTTP Request Node Blank

To make an input connection, drag a link to the HTTP Request node from any node supporting an output connection. To make an output connection, drag a link from the HTTP Request node to any node supporting an input connection.

Flow Builder HTTP Request Node Making Connections

Important

You may have an unlimited number of HTTP Request nodes in a call flow; however, the total number of HTTP requests that may be executed during a call flow is 100.

The HTTP Request node has two output connections: Done and Error. At least one of these connections must be set. These connections represent one of the two possible outcomes for the node when an HTTP request is made to a web service URL.

Done

If the URL is accessible and the request receives a response with a 2xx status code and a variable, if any, is successfully mapped, the flow is routed to the Done connection.

Error

If the URL is not accessible, does not respond within 5 seconds, or returns a non-2xx status code, the flow is routed to the Error connection.

Variables

The HTTP Request node supports system and custom variables that you can use when building requests and when passing data to the next node.

System variables

The following five system (global) variables are available for voice interactions:

Variable Description Example
{{start_time}} The time the interaction started. 2023-08-21T04:02:18Z
{{ani}} The calling number (ANI). 443336006114
{{dnis}} The number dialed (DNIS). 380631234567
{{phone_type}} The type of phone for the ANI. fixed_line
uuid a string containing the UUID of the interaction 07771c38-c159-4965-a878-be0162118b2b

Custom variables

You can include dynamic content in your HTTP requests by leveraging custom variables in the URL field. Click "{ }" to display the Variables menu or manually enter a variable by typing its name enclosed in double brace brackets like this: {{variableName}}.

You can use the variable to contain a complete, correctly formatted URL, or you can mix text with variables to define the URL based on the values contained in the variables.

Here are a few examples for how you can use variables in the URL field:

  • GET {{balanceURL}}, where balanceURL contains a complete URL like this: https://mybankingservice.com/checkbalance?q=39ryw7e
  • https://mybankingservice.com/checkbalance?q={{balanceVariable}}
  • https://mybankingservice.com/{{customerRequest}}?q={{customerVariable}}
  • https://{{serviceBaseURL}}/{{service}}?q={{customerVariable}}

The HTTP Request node enables you to define and use custom variables that you can use to store a data key from a request response using the JSONPath expression.

Custom variables enable you to reuse data from a request response elsewhere in your interaction flow. For example, if you have an endpoint response like this:

{
  "contact": {
    "name": "Richard Sanchez",
    "age": 30
  }
}

You can specify an expression in the JSONPath field to extract and reference the "name" value, Richard Sanchez, like this:

$.contact.name

In this example, the value of the new customer string variable {{customerName}} is $.contact.name. The retrieved data value is Richard Sanchez.

Tip

The JSONPath field supports up to 128 characters.

Passing data to other nodes

You can reference the custom variable from an HTTP Request node in the following nodes:

Send messages

For example, the value for customerName from the previous example can be passed to a Send Message node and used to populate a message with the contact name. Enter {{customerName}} in the body of a message. When the message is sent to the contact, the value stored in customerName is inserted into the message.

Flow Builder HTTP Request Node JSONPath Pass Value Sample Revised

Conditions

Refer to the Introduction in the Conditions node article.

Authentication

The HTTP Request node supports both URL and basic (key-value) request authentication.

URL credentials

Some services require only an API key or username and password as part of the request URL for authentication. To authenticate using an API key or username and password in the URL, include it in the request parameters like the following examples.

Caution

Including sensitive information like usernames, passwords, or API keys directly in the URL is not recommended due to security concerns. Instead, consider using HTTP headers for authentication when possible.

API key

GET https://api.example.com/v1/data?api_key=123456789abcdef

Username and password

GET https://username:password@api.example.com/v1/data

Basic authentication

Basic Authentication is a simple authentication scheme built into the HTTP protocol. It lets you send a username and password encoded in Base64 or other authentication key as part of the HTTP request headers.

The HTTP Request node Header section enables you to include basic authentication into your HTTP requests. In the Header section, specify a key-value pair where the key is Authorization and the value is Basic followed by your secret authorization key value. For example:

Authorization: Basic dXNlcjpwYXNz

Flow Builder Authorization Header

Important

To ensure that your authorization is transmitted securely, make sure your URL uses the HTTPS protocol instead of HTTP.

Configuring the HTTP Request node

To configure an HTTP Request node in your interaction flow, click the HTTP Request node to display the HTTP Request node panel.

Rename the node

Beginning with the September 15 - 19, 2025 release, you may name nodes in Flow Builder. Click a node in the node palette to add it to the flow. The node is added to the flow and is named Node N, where N represents the number of the node; for example, Node 6. Below the node name is the node type, such as Play Audio. Click the node to open the node configuration panel, then click the name of the node to edit it. Enter a new name, then the check mark to save your change.

Method

The HTTP Request node supports two methods, GET and POST. Different configuration options are available, depending on which method you select from the Method menu.

GET Request

To configure a GET request, select GET from the Method menu.

Flow Builder HTTP Request Node Blank GET Revised

URL

Enter the URL of the web service to which you are going to send the request. The URL can include system and custom variables.

Headers

Specify one or more HTTP headers for your request. Headers provide essential information such as content type, authorization, and other metadata needed by the remote endpoint to process the request correctly. Each header includes a key-value pair. For example: "Content-type":"application/json".

Flow Builder HTTP Headers

For each header that you create, you must specify both a key name and a value.

You can use a header to include basic authentication in your request.

In the Key field, specify the name of the request key. All standard JSON keys are supported along with your custom keys.

In the Value field, specify a value for the key. Variables are supported for values so that you can include data from other flow nodes in your request.

You can add up to 10 headers. Click Add header to add a header to the request.

To remove a header, click the X next to it.

Test request

When you enter a URL in the URL field, the Test Request button becomes available. Click the button to verify the URL and see a preview of the response.

If the request fails, the Test request field displays [].

If the request is successful, a JSON response is displayed. For example:

{
  "account": 54321000
  "balance": 684415.39
}

Mapping settings

In the Mapping settings section, specify a value from the response to be assigned to a custom variable you define or specify.

Use the custom variable in other nodes, such as another HTTP Request or Send Message. For more information about using variables with the HTTP Request node, refer to Using the HTTP Request node above.

In the following example, the value for the id parameter, the contact's ID number, is assigned to the customerID variable.

Flow Builder HTTP Request Node GET JSONPath Example Revised

POST Request

To configure a POST request, select POST from the Method menu.

Flow Builder HTTP Request Node Blank POST Revised

URL

Enter the URL of the web service to which you are going to send the request. The request URL can include variables.

Request body

Enter the body of the request as a JSON object. The request can include system and custom variables, including custom variables from other HTTP Request nodes. Click "{ }" to display the Variables menu or manually enter a variable by typing its name enclosed in double brace brackets like this: {{variableName}}. This example uses the {{ani}} system variable and the {{contactID}} custom variable:

{
  "contacts": [
    {
      "phoneNumber": "{{ani}}",
      "contactID": "{{contactID}}",
      "contactSource": "",
      "contactURL": "",
      "priority": ""
    }
  ]
}

Headers

Specify one or more HTTP headers for your request. Headers provide essential information such as content type, authorization, and other metadata needed by the remote endpoint to process the request correctly. Each header includes a key-value pair. For example: "Content-type":"application/json".

Flow Builder HTTP Headers

For each header that you create, you must specify both a key name and a value.

You can use a header to include basic authentication in your request.

In the Key field, specify the name of the request key. All standard JSON keys are supported along with your custom keys.

In the Value field, specify a value for the key. Variables are supported for values so that you can include data from other flow nodes in your request.

You can add up to 10 headers. Click Add header to add a header to the request.

To remove a header, click the X next to it.

Test request

When you enter the request body, the Test Request button becomes available. Click the button to verify the URL and request and see a preview of the response.

Tip

To test a request with a variable, enter a test value instead of the variable name. Once the request returns the expected result, replace the test value with the variable. For example, use a phone number value to test the {{ani}} variable.

If the request fails, the Test request field displays [].

If the request is successful, the expected response is displayed in the Test request field.

Flow Builder HTTP Request Node POST Success Example Revised

Mapping settings

In the Mapping settings section, specify a value from the response to be assigned to the custom variable, such as {{customerName}}.

Use the custom variable in other nodes, such as another HTTP Request or Send Message. For more information about using variables with the HTTP Request node, refer to Using the HTTP Request node above.