The gateway provides a way of receiving real time information of your bot pages directly into your applications, such as page views, upvotes and bot invites. The gateway is very easy to connect to, and even has load balancing to increase performance for large connections.
wss://gateway.botlist.space
All data payloads that are sent should be formatted with JSON, and follow the strict guide below:
{"op": Number, // Required, OP code of the payload"t": Number, // Required, timestamp of when the payload was sent (in milliseconds since 1970)"d": ?Object // Required, may be null, data contained in the payload}
OP Code | Name | Transaction Limit | Description |
0 | Identify | Client → Server | Identifies who is connected to the gateway, contains a list of bot tokens that subscribes to events. |
1 | Heartbeat | Client → Server | The heartbeat is sent to the server, ensures that the connection is still alive. |
2 | Page View | Client ← Server | Sent whenever a user views the bot page. |
3 | Bot Invite | Client ← Server | Sent whenever a user invites the bot. |
4 | Bot Upvote | Client ← Server | Sent whenever the bot is upvoted, contains user data. |
Code | Message | Description |
4000 | Unknown error | Something horrible happened while trying to interpret the payload. |
4001 | Invalid OP code | A payload was sent with an invalid OP code. |
4002 | Invalid payload | The payload was unexpected, or didn't fit the requirements for the OP type. |
4003 | Client failed to identify in time | The client took too long to send an OP 0 Identify payload (timeout is 15 seconds). |
4004 | Invalid identification | None of the sent bot tokens were successful at authentication. |
4005 | Client unresponsive | No heartbeat was sent since 60 seconds of the last one. |
4006 | Server is restarting | The gateway server is restarting, and the client should attempt to reconnect within 5 seconds. |
The first event that should be sent from the client. Identifies who is connected by using a list of bot tokens in an array. These bot tokens will be used as authorization and determine who to send the events to. If the identification was successful, the WebSocket should stay open. If one token wasn't successful at authenticating, it will be ignored. If none of the tokens work, the WebSocket should close with a 4004 Invalid identification
close error. The client can re-send an identify whenever needed.
{"op": 0,"t": 1548535825840,"d": {"tokens": ["63f17d9442e4ef7f679f00323ad1454e1fd1fe59e27137f71fc18deea69b8bfe9ed8bb13651393a597e79591cf10018e","6fdfccaaa1539d48545a4a26b4e84fd927d25733886a0933f6293a500989b04f3a73328c9fbc98e5317858bbb4e4da59"]}}
The heartbeat ensures that the connection is still alive, and that the server shouldn't try to send payloads to a dead client. The payload should be sent in under 60 seconds of each other; 45 seconds is a good number to use. If the server doesn't receive a heartbeat within 60 seconds of the last one, the WebSocket will close with a 4005 Client unresponsive
error.
{"op": 1,"t": 1548535825840,"d": {}}
Sent to the client when a user views the page of a bot that the client has authorized.
{"op": 2,"t": 1548535825840,"d": {"bot": 508415615036424192}}
Sent to the client when a user requests the invite link of a bot.
{"op": 2,"t": 1548535825840,"d": {"bot": 508415615036424192}}
Sent to the client when a user upvotes the bot.
{"op": 2,"t": 1548535825840,"d": {"bot": 508415615036424192,"user": {"id": "507329700402561045","username": "PassTheMayo","discriminator": "1281","avatar": "..."}}}