HTTP Request

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.

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.

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:

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

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.

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

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.

Passing data to other nodes

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

• Other HTTP Request nodes
• Send Message node
• Conditions node
• Route node
• Message node

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.

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.

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

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.

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.

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

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.

POST Request

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

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

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.

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

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

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.