HttpRequest

The HttpRequest action allows your bot to execute HTTP requests, which can be used to get data from external resources and save it into variables.

tip

If you want to execute HTTP requests using JavaScript code snippets rather than action tags, use the $http built-in service instead.

Parameters

Parameter	Type	Description	Required
url	String	Request URL.	Yes
method	String	HTTP request method. Possible values: • GET • POST • DELETE • PUT	Yes
dataType	String	Transferred data type. The value of this parameter determines the Content-Type HTTP header value: • json (default value) — application/json. • xml — application/xml. • text — text/plain. You can also specify the Content-Type header directly in the headers parameter: it will have priority over dataType.	No
body	String	Request body. You can specify it in any format (JSON, XML, plain text) as well as use variables.	No
timeout	Number	Response timeout in milliseconds. If the timeout is exceeded, the dialog will switch to the state specified in the errorState parameter if it is present, or to the script root / otherwise.	No
headers	Array of objects	Request headers. Use the following format for the value: headers = [ { "name": "Header 1 value", "value": "Header 1 value" }, { "name": "Header 2 value", "value": "Header 2 value" } ]	No
vars	Array of objects	Variables that will be used to store data from the response.	No
okState	String	The state the dialog will switch to if the server returns a successful response code (in the range between 200 and 299). The response code is stored in the $session.httpStatus variable.	No
errorState	String	The state the dialog will switch to if the server returns an unsuccessful response code (not in the range between 200 and 299).	No

Saving data to variables

Use the vars variable to save the data from the response to a successful HTTP request.

1. JAICP saves the server response in a local variable called $httpResponse. This variable can only be referenced inside the HttpRequest tag.

   tip

   The response is also saved into session data as $session.httpResponse. Reference this property if you want to use the response data in another state. The property value is overwritten on every new HttpRequest tag call.

2. In the vars parameter value, specify an array of objects with the name and value properties, where:

   • name is a variable name. The evaluated value will be stored in $session.<name>.
   • value is an expression using the $httpResponse variable to access the necessary response properties.
   caution

   Use the following characters for the value of name: Aa–Zz, _, 0–9. The first character should be a letter. JavaScript reserved words are not allowed.

How to copy data from the response

The server returns a response with a random quote text and the name of its author:

{
    "quoteText": "And yet it moves!",
    "quoteAuthor": "Galileo Galilei"
}

To store them into $session.quoteText and $session.quoteAuthor, specify the following value for vars:

vars =
    [
        {
            "name": "quoteText",
            "value": "$httpResponse.quoteText"
        },
        {
            "name": "quoteAuthor",
            "value": "$httpResponse.quoteAuthor"
        }
    ]

How to preprocess the response

The server returns a response with a set of products:

[
    {
        "name": "oranges",
        "price": 150
    },
    {
        "name": "tangerines",
        "price": 200
    }
]

You can use any valid JavaScript expression inside value: for example, to save the necessary product only:

vars =
    [
        {
            "name": "product",
            "value": "_.findWhere($httpResponse, {name: 'tangerines'})"
        }
    ]

How to use

• An imitation of a coin toss using a call to the random.org API:

state: HeadsOrTails
    q!: * {heads * tails} *
    HttpRequest:
        url = https://www.random.org/integers/?num=1&min=0&max=1&col=1&base=2&format=plain
        method = GET
        vars = [{"name": "bit", "value": "parseInt($httpResponse)"}]
        okState = /HeadsOrTails/Answer

    state: Answer
        if: $session.bit
            a: Heads!
        else:
            a: Tails!

• Retrieval of a random quotation using the forismatic.com API:

state: RandomQuote
    intent!: /Random quote
    HttpRequest:
        url = https://api.forismatic.com/api/1.0/?method=getQuote&format=json&lang={{$request.language}}
        method = GET
        vars =
            [
                {
                    "name": "quoteText",
                    "value": "$httpResponse.quoteText"
                },
                {
                    "name": "quoteAuthor",
                    "value": "$httpResponse.quoteAuthor"
                }
            ]
        okState = /RandomQuote/Answer

    state: Answer
        a: {{$session.quoteAuthor}} once said: “{{$session.quoteText}}”

HTTP client limitations

• HttpRequest executes all HTTP requests synchronously. User query processing is suspended until the HTTP request has returned a response.

• You can have at most 15 HttpRequest actions during the processing of a single user query. Should this limit be exceeded, the method will return a response with an error.