Botsquad documentation logo

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

http_get

To make a HTTP GET request you can use:

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

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

http.status_code  200
http.body.url http://httpbin.org/get?foo=bar&test=123
http.body.origin  51.15.41.99
http.body.headers.User-Agent  hackney/1.10.1
http.body.headers.Host  httpbin.org
http.body.headers.Connection  close
http.body.args.test 123
http.body.args.foo  bar

Note that httpbin.org 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)}"

http_post

To make a HTTP POST request you can use:

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

When invoked will return:

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

As you can see the full response body is made available in http.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 http.body.json.

http_post with form encoded data

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

http_post with json encoded data

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

no redirects

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

http_get "http://httpbin.org/redirect/2", redirect: false
say http.status_code

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

Decoder

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 = "https://bsqd.me/api/session/#{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 "http://3rdparty.com/registerwebhook", [url: webhook_url]
end

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}"
end

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.