Skip to content

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

Alternatively, the API key can be added to the URL as a query parameter named api_key, for instance;

https://bsqd.me/api/bot/66bfa5d1-ad06-409f-b7a6-112f5fa94ab5?api_key=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 generic 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)

Furthermore, the payload contains either an action or an action_status field.

For each webhook, it is possible to set up what kind of messages are received on the webhook:

  • All - receive all different payloads
  • All actions - receive all action messages
  • User actions - receive only action messages that the user-side of the conversation is sending
  • Operator actions - receive only action messages that the operator-side of the conversation is sending (e.g. bot messages)
  • Message delivery - receive all action_status update messages.

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",
  "channel": {
    "type": "whatsapp"
  },

  // 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.

Message delivery notifications

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",
  "channel": {
    "type": "whatsapp"
  },

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

Currently, the action_status event for the following channels (click to see the documentation for the status values):

Delivery status in conversation history

When retrieving the Conversation history, the delivery status is available in the delivery_status field on each action object of the result:

{
  "delivery_status": "read",
  "id": "gBGGMWQTIlmfAgmAj1ghwchVbdY",
  "payload": {
    "message": "Hello"
  },
  "time": "2022-04-04T09:27:02.521097Z",
  "type": "text"
},