Botsquad documentation logo

To integrate your chatbot with external APIs you can use http_get, http_post, and the like.


To make a HTTP GET request you can use:

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

The full response (including arguments and decoded JSON response) is mapped to http variables:

http.status_code  200
http.body.headers.User-Agent  hackney/1.10.1
http.body.headers.Connection  close
http.body.args.test 123  bar

Note that returns your request back to you in the response as JSON.

All HTTP 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.

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


To make a HTTP POST request you can use:

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

When invoked will return:

http.status_code  200
http.body.json.value  9 Arjan
http.body.headers.User-Agent  hackney/1.10.1
http.body.headers.Content-Type  application/json
http.body.headers.Content-Length  28
http.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 http.body.json.

http_post with form encoded data

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

http_post with json encoded data

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

no redirects

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

http_get "", redirect: false
say http.status_code

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


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

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

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

Webhook events

The Botsquad platform exposes an endpoint for other parties to call directly into users sessions by triggering on an incoming event:

  event_name = "hello"
  webhook_url = "{session_id}/event/#{event_name}"

where the session_id is a system variable and the event_name variable you set matching the name of your dialog.

To register the postback (assumed a POST here) call your 3rd party using http_post passing the callback URL:

dialog RegisterWebhook do
  http_post "", [url: webhook_url]

Next define a dialog that triggers on the "hello" event, to capture the webhook:

dialog event: "hello" do
  say "hello from the event #{event.payload.hi}"

Similar to the http_get and http_post the request body will be decoded when a decoder is matched (JSON only for now).

You can test the webhook by calling the endpoint yourself: using Curl or just via browser. Don’t forget to copy the sessio_id of the live session you’re trying to test with.