Skip to content

HTTP requests

To integrate your chatbot with external APIs you can use:


Below is an example of an HTTP GET request that uses httpbin. In this example, the returned body is a JSON object that contains all the requests parameters. As you can see, the JSON is automatically transformed to a Map.

dialog get do
  url = ""
  response = http_get "#{url}?foo=bar&test=123"
  say "#{} #{response.body.args.test}"

# response.status_code  200
# response.body.origin
# response.body.headers.User-Agent  hackney/1.10.1
# response.body.headers.Host
# response.body.headers.Connection  close
# response.body.args.test 123
#  bar
  • status_code: HTTP Status code
  • body (this largely depends on what the server sends back):
  • headers: a key-value object with the structure "Header name" => value.

The following HTTP request methods are supported: http_get, http_post, http_put, http_patch, http_delete.

url encoding

When you pass captured information via the URL make sure you encode the information before sending it.

response = http_get "#{url}?param=#{url_encode(variable)}"


To make an HTTP POST request you can use:

dialog post_params do
  response = http_post "", [
    name: "Arjan",
    value: "#{3 * 3}"]
  say "#{} #{response.body.json.value}"

When invoked will set the response variable with the following contents:

response.status_code  200
response.body.json.value  9 Arjan
response.body.headers.User-Agent  hackney/1.10.1
response.body.headers.Content-Type  application/json
response.body.headers.Content-Length  28
response.body.headers.Connection  close  {"value":"9","name":"Arjan"}

As you can see the full response body is made available in and also (when a decoder is matched) as decode structure. In this case the response body was identified as application/json and as such decoded into response.body.json.

http_post with form encoded data

dialog form_post_params do
  response = http_post "", form: [
    name: "Arjan",
    value: "#{3 * 3}"]
  say "#{} #{response.body.form.value}"

http_post with json encoded data

dialog post_headers do
  response = http_post "",
    json: [
      name: "Arjan",
      value: "#{3 * 3}"],
    headers: [
      foo: "Foo",
      "Authorization": "Bar"
  say "hoi"

http_post with XML encoded data

dialog post_headers do
  xml = ["body", [class: "a"], "contents"]
  response = http_post "", xml: xml

This will encode the given xml variable as XML and set the appropriate content-type request header.

In the above example, the XML that is posted is: <body class="a">contents</body>.

http_post with raw body

You can also do a "raw" post request, e.g. for posting XML or some other data type.

dialog content_type do
  response = http_post(
    raw: "<xml>payload</xml>",
    headers: ["Content-Type": "text/xml"]
  say response.body.headers["Content-Type"]

In a raw request, when the content-type header is omitted, it defaults to application/octet-stream.

no redirects

By default, the HTTP request follows any redirect (up to a maximum of 3). To prevent this, pass redirect: false:

response = http_get "", redirect: false
say response.status_code

The output will be "302". The redirect URL will be in the Location header: response.headers["Location"].


Sometimes parties don't set the correct response.body.headers["Content-Type"] and so the response is not decoded. To force a decoder use:

response = http_get "#{url}?foo=bar&test=123", decoder: :json

Currently the system support: :json, :raw and :form.


It is possible to specify a custom timeout value for an HTTP request. The default timeout is 5 seconds, but when an API takes longer than 5 seconds to respond you can specify a timeout: option:

response = http_get "", timeout: 5
say response.error  #  will be true
say response.reason #  will be "timeout"