Bot API rehberi

Portal üzerinden uygulama ve bot token oluşturduktan sonra bot gateway, komut senkronizasyonu, mesaj geçmişi okuma, ek dosya yönetimi, reaction ve interaction response akışlarını kullanabilirsin.

Başlangıç

Bot gateway’e bağlanır, token ile kendini tanıtır, dispatch eventlerini dinler ve komut senkronizasyonu, mesaj geçmişi, ek dosyalar, emoji, reaction ve interaction response için REST kullanır.

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 kontratı

Gateway HELLO ile başlar, sonra IDENTIFY gelir. Trafiği daraltmak için intents alanı eklenebilir. MESSAGE_REACTIONS intent'i MESSAGE_REACTION_ADD ve MESSAGE_REACTION_REMOVE event'lerini getirir. İstemci her heartbeat için zamanında ACK dönmeli, aksi durumda socket bayat sayılıp yeniden bağlanmalıdır.

// 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 akışı

Bot token ile komut senkronize et, mesaj geçmişi oku, context çek, ek dosya yükle, emoji listesini al, reaction ekle ya da sil, voice kanalına katıl ve application command'ler için original response veya follow-up mesajları üret. Komut option tipleri şu an string, integer, number, boolean, user, channel, role, mentionable ve attachment kabul eder.

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 desteği sunucu mesajlarını ve conversation mesajlarını kapsar. Sunucu reaction’ları hedef sunucunun emoji katalogunu ve izin varsa diğer kurulu sunuculardaki custom emojileri kullanabilir. Conversation reaction’ları kullanıcının erişebildiği emoji katalogunu kullanabilir; reaction kullanıcı listesi ve clear-all akışları da artık açıktır.

Interaction kabiliyetleri

Application command dispatch gateway üzerinden akar; botlar interaction ack veya defer yapabilir, original response üretebilir, original responseu düzenleyebilir ve follow-up mesaj gönderebilir. Ephemeral response, component, modal ve autocomplete halen backlogdadır.

// 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

Hatalar ve rate limit

Bot REST yanıtları artık code, message, details ve requestId alanlarını içeren standart bir hata gövdesi döner. Rate limit olan istekler Retry-After ve bucket başlıklarını da döner.

{
  "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"
}

Kalan açıklar

Aşağıdaki alanlar halen mevcut kontrata dahil değil.

Gateway session resume ve invalid-session toparlama henüz bağlı değil.
Ephemeral interaction response henüz desteklenmiyor.
Autocomplete teslimi henüz bağlanmadı.
Component, modal submit ve daha zengin gateway lifecycle eventleri henüz bağlı değil.