Gateway bağlantısı¶

Bir bot, olayları TEBHOS gateway'ine kurduğu WebSocket bağlantısı üzerinden gerçek zamanlı alır. Bu sayfa botun kurduğu bağlantıyı adım adım anlatır; protokolün tamamı gateway başvuru belgesinde yer alır.

Gateway URL'sini alma¶

GET /gateway/bot

Bağlanılacak WebSocket URL'sini döndürür. Kimlik doğrulama bot token'ıyla yapılır; kullanıcı token'ı veya eksik token 401 döndürür. Hız sınırı: istemci başına dakikada 60.

curl https://tebhos.com/api/v1/gateway/bot \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN"

{
  "url": "wss://tebhos.com/ws",
  "shards": 1,
  "session_start_limit": {
    "total": 1000,
    "remaining": 999,
    "reset_after": 14400000,
    "max_concurrency": 1
  }
}

Bağlantı yaşam döngüsü¶

connect  wss://tebhos.com/ws?v=1&encoding=json
  <- Hello           (op 10)  { "heartbeat_interval": 41250 }
  -> Identify        (op 2)   { "token": "...", "properties": { ... } }
  <- READY           (op 0)   session_id, user, ...
  <- GUILD_CREATE    (op 0)   one per guild the bot is in
  -> Heartbeat       (op 1)   every heartbeat_interval ms
  <- Heartbeat ACK   (op 11)
  <- MESSAGE_CREATE  (op 0)   ... and every other event

1. Bağlanma¶

/gateway/bot yanıtındaki url adresine şu sorgu parametreleriyle bir WebSocket açılır:

wss://tebhos.com/ws?v=1&encoding=json

Her iki yöndeki her çerçeve bir JSON nesnesidir:

Gönderilen bir çerçeve en fazla 4096 bayt olabilir.

2. Hello alma¶

Gateway hemen milisaniye cinsinden heartbeat_interval içeren Hello (op 10) gönderir (şu an 41250).

3. Identify¶

Bot token'ıyla Identify (op 2) gönderilir. token alanına token yalın hâliyle konur. REST Authorization başlığındaki gibi baştaki bir Bot öneki de kabul edilir ve soyulur; böylece başlık değerini yeniden kullanan kütüphaneler değişiklik gerektirmeden çalışır. Bearer kabul edilmez.

{
  "op": 2,
  "d": {
    "token": "1290847135893127168.q3JxY2V0...W5k",
    "properties": { "os": "linux", "browser": "my-bot", "device": "my-bot" }
  }
}

Eksik veya hatalı biçimli bir alan bağlantıyı 4002 ile kapatır. Geçersiz bir token bağlantıyı 4004 ile kapatır.

Bir bağlantı en fazla 2.500 sunucu taşıyabilir. Daha fazla sunucudaki bir bot shard kullanmak zorundadır: shard_count kadar bağlantı açılır ve her birine 0 ile shard_count - 1 arasında farklı bir shard_id gönderilir. Bir sunucu (guild_id >> 22) % shard_count numaralı shard'a düşer. shard dizisi yoksa ya da bir shard yine 2.500'den fazla sunucu tutacaksa gateway bağlantıyı 4011 (Sharding gerekli) ile kapatır. Hatalı biçimli bir çift bağlantıyı 4010 ile kapatır. /gateway/bot her zaman 1 shard önerir; bu yüzden shard_count değerini sunucu_sayısı / 2500 üzerinde pay bırakarak kendiniz seçin. Doğrudan mesaj ve bir sunucuya ait olmayan diğer olayları yalnızca shard 0 alır; bkz. Shard filtresi.

Intent yoktur: bot, görebildiği sunucular ve kanallar için tam mesaj içeriği dahil her olayı alır. Gerekmeyen trafiği azaltmak için ignored_events kullanılır.

4. READY ve GUILD_CREATE alma¶

Oturum hazır olduğunda gateway READY gönderir. Bir bot için READY boş bir guilds dizisi taşır; ardından her sunucu kendi GUILD_CREATE gönderimiyle gelir (bir sunucu geçici olarak kullanılamıyorsa unavailable: true ile GUILD_DELETE).

READY içinden şu alanlar saklanmalıdır:

Bot bağlıyken biri onu başka bir sunucuya eklerse gateway açık oturumu o sunucuya bağlar ve onun için bir GUILD_CREATE gönderir; yeniden bağlanmak gerekmez.

5. Heartbeat¶

Her heartbeat_interval milisaniyede bir, d alanı alınan son sıra numarası s olacak şekilde (ilk gönderimden önce null) Heartbeat (op 1) gönderilir. Gateway, Heartbeat ACK (op 11) ile yanıt verir.

{ "op": 1, "d": 42 }

• Gateway bota op 1 gönderirse hemen bir heartbeat geri gönderilmelidir. Gateway bunu, aralığın yaklaşık %90'ı boyunca bottan haber alamadığında yapar.
• Son onaylanan heartbeat'ten sonraki 45 saniye içinde heartbeat gelmezse gateway bağlantıyı 4009 ile kapatır.
• Oturumun hiç göndermediği bir sıra numarası içeren heartbeat bağlantıyı 4007 ile kapatır.
• Bir heartbeat gönderildikten sonra bir sonrakinin zamanı gelmeden ACK alınmazsa bağlantı ölü sayılmalıdır: bağlantı kapatılır ve resume yapılır.

Her gönderimdeki s izlenmelidir: her olayda bir artar ve heartbeat ile resume içinde gönderilen değer budur.

Bağlantı koptuktan sonra resume¶

Bağlantı düşerse yeni bir bağlantı açılır, Hello beklenir ve Identify yerine Resume (op 6) gönderilir:

{
  "op": 6,
  "d": {
    "token": "1290847135893127168.q3JxY2V0...W5k",
    "session_id": "the session_id from READY",
    "seq": 42
  }
}

Üç alanın hepsi zorunludur. token, Identify'da nasıl gönderildiyse (Bot önekiyle ya da öneksiz) aynen gönderilir: gateway onu oturumu açan token'la karşılaştırır. Başarılı olursa gateway kaçırılan olayları yeniden oynatır, ardından RESUMED gönderir. Bir oturum, bağlantı düştükten sonra 60 saniye boyunca sürdürülebilir.

Gateway Invalid Session (op 9, d: false) ile yanıt verirse oturum yok olmuştur: 1–5 saniye beklenir ve yeni bir Identify gönderilir. Reconnect (op 7) gönderirse bağlantı kapatılır ve yeni bir bağlantı üzerinde resume yapılır.

Tablonun tamamı İşlem kodları ve kapanış kodları sayfasındadır.

Özel durum ayarlama¶

Bot, durumunu (presence) TEBHOS uygulamalarının kullandığı komutla, Presence Update (op 3) ile ayarlar. TEBHOS'ta "Oynuyor ..." veya "Dinliyor ..." gibi etkinlikler yoktur: activities alanı yok sayılır. Bot bir durum ve bir özel durum, yani isteğe bağlı emojili kısa bir metin gösterebilir.

{
  "op": 3,
  "d": {
    "status": "online",
    "custom_status": { "text": "Type !help", "emoji_name": "🎵" }
  }
}

• READY'den sonra gönderilir. Identify'daki presence alanı da aynı alanları kabul eder; bkz. Başlangıç durumu nesnesi.
• Unicode emoji emoji_name alanına yazılır ve olduğu gibi gösterilir. Özel emoji (emoji_id) yalnızca TEBHOS Pro'lu hesaplar için yayımlanır; bu yüzden bir botta genellikle çıkarılır, metin korunur. Hiçbir emojiyi belirtmeyen bir emoji_id özel durumun tamamını reddettirir ve önceki özel durum yerinde kalır.
• expires_at, özel durumun temizleneceği ISO 8601 zamanıdır.
• Durumu invisible olan bir bot herkese çevrim dışı ve özel durumsuz görünür.
• Gateway tek bir bağlantıda 20 saniyede 5 durum güncellemesi kabul eder; fazlasını hata vermeden atar.

Kuralların tamamı Presence Update bölümündedir.

Sesli kanala katılma¶

Bot sese TEBHOS uygulamalarıyla aynı yoldan katılır: gateway'den kanalda yer ister, ardından gateway'in döndürdüğü kimlik bilgisiyle medya sunucusuna (LiveKit) bağlanır. Bunun için ayrı bir HTTP yolu yoktur.

1. Sunucunun GUILD_CREATE olayı beklenir. İçindeki voice_states, kimin hangi sesli kanalda olduğunu gösterir.

2. connection_id olmadan Voice State Update (op 4) gönderilir; bu yeni bir bağlantı açar. Kimlikler string olarak gönderilir.

   {
     "op": 4,
     "d": {
       "guild_id": "1189375284394692608",
       "channel_id": "1189375284394692610",
       "self_mute": false,
       "self_deaf": false
     }
   }
   

3. Gateway Kanalı Görüntüle ve Bağlan izinlerini, kanalın kullanıcı sınırını ve botun zaman aşımında olup olmadığını denetler. Katılıma izin verilirse oturum token, endpoint, channel_id ve connection_id içeren bir VOICE_SERVER_UPDATE alır. connection_id saklanır. Kanalı görebilen her oturum bot için bir VOICE_STATE_UPDATE alır.

4. Sunucuda çalışan bir LiveKit SDK'sı (Node.js için @livekit/rtc-node) ile token kullanılarak endpoint adresine bağlanılır ve bir ses izi yayımlanır. Konuş izni yoksa bot suppress: true ile kabul edilir ve kimse onu duymaz.

5. Ayrılmak için channel_id: null ve connection_id ile op 4 gönderilir, ardından medya sunucusuyla bağlantı kesilir. connection_id olmadan ayrılma isteği reddedilir.

   {
     "op": 4,
     "d": {
       "guild_id": "1189375284394692608",
       "channel_id": null,
       "connection_id": "the connection_id from VOICE_SERVER_UPDATE"
     }
   }
   

Bir ses botunun ele alması gerekenler:

• Reddedilen bir katılım (eksik izin, dolu kanal, zaman aşımındaki bot) hiçbir olay üretmez. VOICE_SERVER_UPDATE bir zaman aşımıyla, örneğin 15 saniye, beklenir.
• Aynı sunucu için sonradan gelen bir VOICE_SERVER_UPDATE (bölge değişikliği veya taşınma sonrası) yeni bir token taşır. Medya sunucusuna bu token'la yeniden bağlanılır.
• Botun kendi kullanıcısı için channel_id: null taşıyan bir VOICE_STATE_UPDATE, bir moderatörün botu çıkardığı ya da kanalın silindiği anlamına gelir. Medya bağlantısı kapatılır; op 4 göndermeye gerek yoktur.
• Kanalın uçtan uca şifreleme zorunluluğu botlara uygulanmaz.
• Saniyede yalnızca ilk iki ses güncellemesi hemen işlenir; sonrakiler gecikebilir veya birleştirilebilir.

Yerleşim, izinler ve kapasite Ses sayfasında, tüm alanlar Voice State Update bölümünde anlatılır.

Sınırlar¶

Ayrıntılar için bkz. Gateway sınırları ve hız sınırları.

Sonraki adım: mesajlara yanıt verme.