Bot API guide

After creating an application and bot token in the portal, you can connect through the bot gateway, sync commands, read message history, send and edit messages, manage attachments, react to messages, and answer interactions with defer/response/follow-up flows.

Getting started

A bot connects to the gateway, identifies with its token, listens for dispatch events, and uses REST for command sync, message history, attachments, emoji, reactions, and interaction responses.

1. Generate a bot token in the Developer Portal.
2. Connect to ${GATEWAY_ORIGIN}/gateway/bot and identify with the token.
3. Listen for DISPATCH events and ACK heartbeats on time.
4. Use REST for command sync, message history, attachments, emoji, reactions, interaction responses, and voice joins.

Gateway contract

The gateway starts with HELLO, then IDENTIFY. You may include intents to narrow delivery. MESSAGE_REACTIONS now delivers MESSAGE_REACTION_ADD and MESSAGE_REACTION_REMOVE events. The client must reply to every heartbeat in time or treat the socket as stale and reconnect.

// HELLO
{
  "op": "HELLO",
  "d": { "heartbeatInterval": 25000 }
}

// IDENTIFY
{
  "op": "IDENTIFY",
  "d": {
    "token": "<bot-token>",
    "intents": ["APPLICATION_COMMANDS", "SERVER_MESSAGES", "SERVER_VOICE", "MESSAGE_REACTIONS"]
  }
}

// HEARTBEAT / ACK
{ "op": "HEARTBEAT" }
{ "op": "HEARTBEAT_ACK" }

// READY
{
  "op": "DISPATCH",
  "t": "READY",
  "d": {
    "applicationId": "<application-id>",
    "botUserId": "<bot-user-id>",
    "username": "music-bot",
    "displayName": "Music Bot",
    "serverIds": ["<server-id>"]
  }
}

// APPLICATION_COMMAND
{
  "op": "DISPATCH",
  "t": "APPLICATION_COMMAND",
  "d": {
    "interactionId": "<interaction-id>",
    "serverId": "<server-id>",
    "channelId": "<channel-id>",
    "name": "play",
    "rawInput": "/play https://example.com/audio.mp3"
  }
}

// MESSAGE_REACTION_ADD
{
  "op": "DISPATCH",
  "t": "MESSAGE_REACTION_ADD",
  "d": {
    "serverId": "<server-id>",
    "channelId": "<channel-id>",
    "messageId": "<message-id>",
    "userId": "<user-id>",
    "emoji": {
      "kind": "custom",
      "customEmojiId": "<emoji-id>",
      "customEmojiName": "party"
    },
    "count": 3
  }
}

REST flow

Use the bot token to sync commands, read channel history, fetch message context, upload attachments, resolve emoji lists, add or remove reactions, join voice channels, and produce original responses or follow-up messages for application commands. Command options currently accept string, integer, number, boolean, user, channel, role, mentionable, and attachment.

PUT ${API_ORIGIN}/api/bot/v1/commands
{
  "commands": [
    {
      "name": "play",
      "description": "Play a track in voice",
      "options": [
        { "name": "url", "description": "Track URL", "type": "string", "required": true }
      ]
  }
]
}

GET ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages?before={messageId}&limit=50
GET ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}
GET ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}/context?before=25&after=25

POST ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages
{
  "content": "Now playing: track title"
}

POST ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages
{
  "content": "Replying to a message",
  "replyToMessageId": "<message-id>"
}

PATCH ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}
{
  "content": "Edited content"
}

DELETE ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}

POST ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/attachments/upload-session
GET ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}/attachments/{attachmentId}/access-url

GET ${API_ORIGIN}/api/bot/v1/servers/{serverId}/emojis
GET ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions
DELETE ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions
PUT ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/me
DELETE ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/me
DELETE ${API_ORIGIN}/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/users/{userId}

POST ${API_ORIGIN}/api/channels/{channelId}/interactions/commands
{
  "commandId": "<registered-command-id>",
  "rawInput": "/play https://example.com/audio.mp3"
}

POST ${API_ORIGIN}/api/bot/v1/interactions/{interactionId}/ack
POST ${API_ORIGIN}/api/bot/v1/interactions/{interactionId}/defer
POST ${API_ORIGIN}/api/bot/v1/interactions/{interactionId}/response
PATCH ${API_ORIGIN}/api/bot/v1/interactions/{interactionId}/response
POST ${API_ORIGIN}/api/bot/v1/interactions/{interactionId}/follow-ups

Reaction support covers server messages and conversation messages. Server reactions can use custom emoji from the target server or other joined servers when the actor has permission. Conversation reactions can use the current user catalog of accessible emoji, and reaction user lists plus clear-all flows are now exposed.

Interaction capabilities

Application commands are dispatched through the gateway, and bots can ack or defer interactions, create an original response, edit the original response, and send follow-ups. Ephemeral responses, component interactions, modals, and autocomplete are still backlog items.

// Current bot interaction support
// - APPLICATION_COMMAND dispatch
// - ack or defer via POST /api/bot/v1/interactions/{interactionId}/ack|defer
// - original response create/edit and follow-up REST flows
// - no ephemeral, components, modal submit, or autocomplete delivery yet

Errors and rate limits

Bot REST responses now include a standard error body with code, message, details, and requestId. Rate limited requests also return Retry-After and bucket headers so clients can back off safely.

{
  "code": "bot_validation_error",
  "message": "Mesaj 1 ile 2000 karakter arasinda olmali.",
  "details": {
    "field": "content"
  },
  "requestId": "0HNHQKQ0J9Q4N:00000001"
}

429 Too Many Requests
Retry-After: 5
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710000000

{
  "code": "bot_rate_limited",
  "message": "Rate limit exceeded.",
  "details": {
    "retryAfterSeconds": 5
  },
  "requestId": "0HNHQKQ0J9Q4N:00000002"
}

Remaining gaps

These areas are still not part of the current contract.

Gateway session resume and invalid-session recovery are not wired up yet.
Ephemeral interaction responses are not supported yet.
Autocomplete delivery is not wired up yet.
Components, modal submits, and richer gateway lifecycle events are not wired up yet.