Skip to main content

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

ParameterTypeDescriptionRequired
urlStringRequest URL.Yes
methodStringHTTP request method. Possible values:
• GET
• POST
• DELETE
• PUT
Yes
dataTypeStringTransferred 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
bodyStringRequest body. You can specify it in any format (JSON, XML, plain text) as well as use variables.No
timeoutNumberResponse 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
headersArray of objectsRequest 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
varsArray of objectsVariables that will be used to store data from the response.No
okStateStringThe 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
errorStateStringThe 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. Tovie Platform 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.

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