Botsquad documentation logo

All REST calls need authorization using an API token. This token can be found on the “settings” page in the “web interface” part of the connections page in the Botsquad studio.

The authorization header is specified as follows:

Authorization: Bearer f181eab8c44ef9ff8d6fedbed7692b0b

Bot endpoints

GET /api/bot/:id

Retrieves generic information about the bot.

    "inserted_at": "2017-11-07T13:42:43.821461",
    "organisation": "ACME",
    "profile_picture": "",
    "purpose": "This bot is an example bot",
    "title": "ExampleBot",
    "updated_at": "2017-12-05T22:16:08.609698",
    "web": {
        "domains": null,
        "shortname": "example"

Note - this is the only endpoint that does not need authentication.

GET /api/bot/:id/presence

Retrieves information about the users that are currently interacting with the bot.

    "presence": [
            "bot_id": "618c2dc8-25e8-4006-8c22-cb2b770eeec8",
            "first_name": "Arjan",
            "frontend": "studio",
            "last_name": "Scherpenisse",
            "profile_picture": "",
            "session_id": "89dee23f-d462-4a30-bd0c-9523ddb6d4e0",
            "status": "online",
            "user_id": "studio:ed9d9470-0f94-4912-925a-50f5d7b6321a",
            "user_message_count": 1

A list is returned under the presence key, which lists all the users which are currently in an active session with the bot.

POST /api/bot/:id/:user_id/event/:event

This allows you to send an event to an ongoing chat session, given the bot and the user id. The (JSON) payload of the request is received in the bot as the event.payload property.

Given the following part of bot script:

dialog event: "message" do
  say "I received a message!"
  say event.message

Then, when you post the body {"message": "hello"} to the following URL of the bot:

POST /api/bot/618c2dc8-25e8-4006-8c22-cb2b770eeec8/asdf890/event/message

The message event will be triggered and the bot will say “I received a message!”, followed by the message from the POST payload.

Session endpoint

POST /api/session/:id/event/:event

Identical to POST /api/bot/:id/:user_id/event/:event, however, this version allows you to address a chat session by its session ID rather than the combination of user and bot id.

GET /api/session/presence

Identical to GET /api/bot/:id/presence, however, this version allows you to retrieve the bot’s presence given a session ID of the given bot.