Skip to main content

Notifications

BotiCord can send you notifications about events with your bot or server. You can receive notifications in WebSocket and HTTPs WebHooks.

WebSocket​

WebSocket this is the basic way to receive notifications about actions with bots/servers.

How to connect​

In short:

  1. connect to wss://gateway.boticord.top/websocket/;
  2. send client hello: {"event":"auth","data":{"token":"token from boticord user settings"}};
  3. receive server hello: {"event":"hello","data":{"id":"connection id"}};
  4. periodically send ping: {"event":"ping","data":{}};
  5. receive ping response: {"event":"pong","data":{}};
  6. receive server notification:
{
  "event": "notify",
  "data": {
    "type": "comment_added", // NotifyTypes
    "payload": null, // any json data or null
    "affected": "722424773233213460", // affected resource id,
    "user": "511887819153866762", // id of the user who triggered this notification,
    "happened": 1688747542930 // unix timestamp ms
  }
}

In detail:

  1. Your program (hereinafter referred to as the client) needs to establish a connection along the path wss://gateway.boticord.top/websocket/;
  2. The client must send the message as a valid JSON: {"event":"auth","data":{"token":"..."}}. Property token should contain valid API token from owner settings: https://boticord.top/me.
  3. After the client sends the message to the server, the server must respond with: {"event":"hello","data":{"id":"special ID of your client (not a bot and not a server)"}
  4. If the server did not respond or responded with something else, try again later or fix the error that was reported to you server (usually, an invalid token is specified, or it is missing altogether)
  5. Periodically, the client must send a message to the server: {"event":"ping","data":{}}. The server must respond with the same message: {"event":"pong","data":{}}. The client must send a ping at least every 90 seconds, otherwise the server will consider the client disconnected and close the connection.
  6. Server notifications are sent in the following format:
{
  "event": "notify",
  "data": {
    "type": "comment_added", // one of notify types. see NotifyTypes
    "payload": null, // any additional data in JSON (for example, review content), OR null
    "affected": "722424773233213460", // id of the resource about which the event occurs
    "user": "511887819153866762", // id of the user who triggered this notification
    "happened": 1688747542930 // UNIX timestamp in milliseconds when the event occurred
  }
}

How disconnections occur​

  1. If the API token has been deleted or regenerated, the server will terminate the WebSocket connection.
  2. The server can also restart and disconnect all current connections.
  3. The server may terminate the connection if the client does not send ping-pong requests for more than 90 seconds. In any other cases, the server does not disconnect the client, but the client can safely disconnect at any time. If the connection is lost, your client should try to reconnect, observing the global rate limit of 15 attempts in 10 seconds, until the connection is established again, then you need to repeat authorization process.

HTTPs WebHooks​

We can also send you notifications over HTTPs by making POST requests to the address you specified. This method is easier to implement, but it is less reliable than WebSocket, and it is not suitable for everyone.

Preparing your server​

In short:

  1. Open port 80 for http or 443 for https, for subnet 2a06:98c0::/29 (AS132892 - Cloudflare, Inc);
  2. Check if IPV6 is working on your server;
  3. Accept POST requests at the address specified in the profile settings on the BotiCord & reply with 200 OK;
  4. Check the correctness of the requests using the token from the bot settings, which we pass in the X-Boticord-Token header.

In detail:

  1. BotiCord uses IPV6 addresses from 2a06:98c0::/29 subnet ( AS132892 - Cloudflare, Inc) to send notifications. This means that any IPV4 addresses are not suitable. You won't be able to receive notifications if you try to do this over direct IPV4. This includes, for example, your PCs and IPV4 issued by your ISP for Internet access, as well as cloud servers supplied with IPV4. If you have a cloud server, so you most likely have a domain or the ability to connect to a tunnel broker, and if you use Cloudflare for your domain, just create a subdomain or transform rule or allocate a separate endpoint in your API, if there is one.
  2. You need to create a server that can receive our POST requests and work 24/7. Also, your server should respond with a status of 200 if everything went well. Your server should not be too slow, otherwise the notification will not come. An attempt to send any specific notification from our side is made exactly 1 time. If your server is not able to receive a notification, it will go into oblivion (only if you do not use receiving notifications via HTTPs WebHooks. In this case, the notification is duplicated both there and there).
  3. We have added additional header settings to add to our POST requests to your servers. You can use them, for example, to authorize our server in Cloudflare Access. You can also set special headers with unique values to verify that the request came from us. By default, we expect that you will check the correctness of the request by the token that we pass along with the request in the X-Boticord-Token header.
  4. We do not recommend using HTTP instead of HTTPS for a server that accepts notifications. If you use Cloudflare, please make sure that the connection between Cloudflare and your server is secure and passes through HTTPS. We transfer the token from your profile settings in the X-Boticord-Token header as confirmation that the request came from us. Take security seriously.
  5. It is necessary to open port 80 for http or 443 for https, for the subnet 2a06:98c0::/29. You can check whether requests from us are being processed using a special button in the profile settings. It will send a POST request to the specified address with test notification.
  6. Accept requests and check their correctness using the token from your profile settings on BotiCord, it comes along with notification. Headers:
Content-Type: application/json
X-Boticord-Token: token from settings
X-Boticord-Affected: id of the resource about which the event occurs, for example, the ID of the review
...your headers

NotifyTypes​

General structure of notifications​

{
   "type": "notify type",
   "payload": {},
   "id": "bot/server id",
   "user": "id of the user who triggered this notification",
   "happened": 1688322825141,
   "webhookSettings": {
      "enabled": true,
      "headers": {
         "Custom-Header": "custom headers (they will also be in the request headers) or here will be empty object"
      },
      "url": "the link where the request was sent, or null",
      "token": "token from the bot/server owner's API settings"
   }
}

payload - this is an object that contains additional data that may be useful for processing notifications.

happened this is the UNIX timestamp in milliseconds when the event occurred.

BotiCord may also send other notifications not listed here.

UP​

Type: up_added Payload:

{
   "upCount": 1
}

upCount - this is the number of UPs that the bot/server received. Comes taking into account the multiplier for the boosts.

New review​

Type: comment_added Payload:

{
   "content": "review content",
   "rating": 5
}

rating - this is the rating of the review from 1 to 5.

Review edited​

Type: comment_edited Payload:

{
   "content": "review content",
   "rating": 3
}

rating - this is the rating of the review from 1 to 5. The content/Rating of the old review is not sent.

Review removed​

Type: comment_removed Payload:

{
   "content": "review content",
   "rating": 3
}

rating - this is the rating of the review from 1 to 5.