Developer docs

Wait for ready

JavaScript connect starts the Socket.IO connection; it does not wait for the server’s ready event. Put voice joins and work that needs the live gateway in a ready handler. Python connect awaits the socket connection; Python also exposes ready. Register all handlers before connecting.

bot.on('ready', data => {
  console.log('Connected as', data.userId);
});
await bot.connect();

Listen for messages

Without Message Content, delivery is limited to registered text commands, explicit mentions and the bot’s own DMs. The SDK ignores automated messages by default to avoid bot loops. Message data keeps camelCase JSON keys in both languages.

bot.on('message.create', async message => {
  if (message.channelId && message.content?.trim() === '!hi') {
    await bot.send(message.channelId, 'Hello!', { clientId: `hello-${message.id}` });
  }
});

Replay and ownership

One live gateway session is allowed per bot. A new connection replaces an older one. Both SDKs reconnect with bounded backoff and replay handling. Delivery can repeat within the retained history; the built-in duplicate cache is memory-only.

Persist your own operation IDs for effects such as payments or external jobs. A failed handler is recorded and acknowledged so later events can continue; retry your business operation explicitly.

Replay retention is ten minutes, with a 2,000-event / 2 MiB queue cap per application. A ready event with resyncRequired means the previous cursor is outside retained history. Refetch the application state your bot needs.

Gateway reconnection does not automatically rejoin voice. Losing the gateway stops playback; rejoin explicitly after you decide it is appropriate.