REST API

This page documents the Botsquad REST API.

Authorization¶

All REST calls need authorization using an API token. The API token can be found in the studio, under Settings → Connect → REST API.

The authorization header is specified as follows:

Authorization: Bearer f181eab8c44ef9ff8d6fedbed7692b0b

REST endpoints¶

Webhook events¶

It is possible to set up a webhook when connecting the REST API channel.

Each webhook endpoint that is added to the bot will receive POST requests whenever an event in the bot happens, e.g. when the bot sends a message or the user sends a message, or when the message status changes.

A webhook JSON message always contains the following fields:

• bot_id - The ID of the bot (= bot.id)
• user_id - The ID of the user (= user.user_id)
• conversation_id - The ID of the conversation (= conversation.g)

Action events¶

When the bot or the user sends an action, next to the generic fields this JSON object will also contain an action field.

The POST payload for the webhook request will look something like this:

{
  // generic fields
  "bot_id": "17fa89f0-d3c4-4cd4-bd9c-b4da2c0a9099",
  "conversation_id": "a9fe87f987fa9e87fe9a",
  "user_id": "d9d9470-0f94-4912-925a-50f5d7b6321a",

  // the actual action (chat event) that is sent
  "action": {
    "delay": 1000,
    "id": "6ca85481-c5df-4b7f-912d-164f8e1905b4",
    "payload": {
      "message": "Hi there 👋 "
    },
    "time": "2021-04-12T12:38:04.475085Z",
    "type": "text"
  }
}

The Chat Message Specification contains more information on how a chat action can look.

Action status events¶

Some channels provide information on the status change of sent messages, for instance, whether messages have been delivered to the user, whether it has been read, etc.

When the status of an action changes, next to the generic fields this JSON object will also contain an action_status field:

{
  // generic fields
  "bot_id": "17fa89f0-d3c4-4cd4-bd9c-b4da2c0a9099",
  "conversation_id": "a9fe87f987fa9e87fe9a",
  "user_id": "d9d9470-0f94-4912-925a-50f5d7b6321a",

  // the status of the given action is changed:
  "action_status": {
    "id": "6ca85481-c5df-4b7f-912d-164f8e1905b4",
    "status": "delivered"
  }
}

Currently, the action_status event is only sent for Whatsapp through the Twilio provider.

The value of the status field can contain any of the message status values Twilio sends.