Skip to content

HTTP requests

To integrate your chatbot with external APIs you can use:

http_get

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 = "http://httpbin.org/get"
  response = http_get "#{url}?foo=bar&test=123"
  say "#{response.body.args.foo} #{response.body.args.test}"
end

# response.status_code  200
# response.body.origin  51.15.41.99
# response.body.headers.User-Agent  hackney/1.10.1
# response.body.headers.Host  httpbin.org
# response.body.headers.Connection  close
# response.body.args.test 123
# response.body.args.foo  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)}"

http_post

To make an HTTP POST request you can use:

dialog post_params do
  response = http_post "http://httpbin.org/post", [
    name: "Arjan",
    value: "#{3 * 3}"]
  say "#{response.body.json.name} #{response.body.json.value}"
end

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

response.status_code  200
response.body.url http://httpbin.org/post
response.body.origin  51.15.41.99
response.body.json.value  9
response.body.json.name Arjan
response.body.headers.User-Agent  hackney/1.10.1
response.body.headers.Host  httpbin.org
response.body.headers.Content-Type  application/json
response.body.headers.Content-Length  28
response.body.headers.Connection  close
response.body.data  {"value":"9","name":"Arjan"}

As you can see the full response body is made available in response.body.data 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 "http://httpbin.org/post", form: [
    name: "Arjan",
    value: "#{3 * 3}"]
  say "#{response.body.form.name} #{response.body.form.value}"
end

http_post with json encoded data

dialog post_headers do
  response = http_post "http://httpbin.org/post",
    json: [
      name: "Arjan",
      value: "#{3 * 3}"],
    headers: [
      foo: "Foo",
      "Authorization": "Bar"
    ]
  say "hoi"
end

http_post with XML encoded data

dialog post_headers do
  xml = ["body", [class: "a"], "contents"]
  response = http_post "http://httpbin.org/post", xml: xml
end

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(
    "http://httpbin.org/anything",
    raw: "<xml>payload</xml>",
    headers: ["Content-Type": "text/xml"]
  )
  say response.body.headers["Content-Type"]
  say response.body.data
end

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 "http://httpbin.org/redirect/2", redirect: false
say response.status_code

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

Decoder

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.

Timeout

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 "http://httpbin.org/delay/10", timeout: 5
say response.error  #  will be true
say response.reason #  will be "timeout"