falafy
EN
Download free

Public API v1 · @falafy/bot

Gateway and intents

One WebSocket per bot receives server and DM events in real time, filtered by the intents you asked for.

Connect

  1. Get the URL from GET /api/v1/gateway/bot (today wss://falafy.com.br/gateway).
  2. Send {"op":"IDENTIFY","token":"Bot YOUR_TOKEN","intents":513} within 10 seconds.
  3. Receive READY with your user, servers, channels and roles, and the resumeId.
  4. Send {"op":"PING"} every 30 seconds (the server closes connections silent for more than 75 s). Each event arrives as {"op":"EVENT","event":{"t":"MESSAGE_CREATE","d":{...}},"seq":42}.

Resume after a drop

Keep the READY resumeId and the last seq. When reconnecting, send {"op":"RESUME","token":"Bot YOUR_TOKEN","sessionId":"RESUME_ID","seq":42}: missed events arrive in order, then RESUMED. If you get INVALID_SESSION, IDENTIFY again. The session keeps its intents.

Intents

Add up the values of the intents the bot needs. Without intents, every non-privileged one applies. Those marked ★ are privileged: turn each one on in the portal before asking for it.

IntentValueEvents
SERVERS1SERVER_CREATE/DELETE, CHANNEL_*, ROLE_*, CHANNELS_SYNC, THREAD_*
SERVER_MEMBERS ★2MEMBER_JOIN, MEMBER_LEAVE, MEMBER_UPDATE
SERVER_MODERATION4MEMBER_WARNING
SERVER_EXPRESSIONS8EXPRESSIONS_UPDATE
SERVER_VOICE_STATES128VOICE_STATE_UPDATE
SERVER_PRESENCES ★256PRESENCE_UPDATE, ACTIVITY_UPDATE
SERVER_MESSAGES512MESSAGE_CREATE/UPDATE/DELETE, PIN_*
SERVER_MESSAGE_REACTIONS1024REACTION_ADD, REACTION_REMOVE
SERVER_MESSAGE_TYPING2048TYPING
DIRECT_MESSAGES4096MESSAGE_* (DM), DM_CREATE
DIRECT_MESSAGE_REACTIONS8192REACTION_* (DM)
DIRECT_MESSAGE_TYPING16384TYPING (DM)
MESSAGE_CONTENT ★32768content / embeds / attachments / components

INTERACTION_CREATE always arrives, with no intent. So do the bot’s own server joins and leaves.

Close codes

  • 4000 bad frame · 4002 no IDENTIFY in time · 4003 no heartbeat: reconnect and RESUME.
  • 4001 invalid or rotated token: don’t reconnect with the same token.
  • 4004 too many connections for the same bot.
  • 4013 invalid intents · 4014 privileged intent not enabled in the portal.

Scale

Today a bot uses one connection (up to 10 at once per bot). Sharding isn’t needed; if it ever is, it will come as a new IDENTIFY option without breaking connected bots.