İstemci komutları¶

İstemciler komutları Gateway WebSocket'i üzerinden, op içinde bir tamsayı işlem kodu (opcode) ve d içinde komut verisiyle gönderir. Bir komut bir Dispatch, bir kapanış çerçevesi ya da hiç yanıt üretmeyebilir.

Heartbeat, Identify ve Resume dışındaki her komut bağlı bir oturum gerektirir. Bunlardan birini çok erken göndermek bağlantıyı 4003 koduyla ve Not authenticated nedeniyle kapatır. Heartbeat her açık durumda kabul edilir. Identify ve Resume yalnızca bağlı bir oturum yokken kabul edilir.

Komut dizini¶

Yük işleme¶

Boyut, açma veya çözme denetimlerinden geçemeyen bir çerçeve bağlantıyı kapatır. Nesne dışında bir şeye çözülen bir çerçeve 4002 koduyla ve Decode failed nedeniyle, op içermeyen bir nesne ise 4002 ve Invalid payload nedeniyle kapatır.

TEBHOS, bu denetimlerden geçen her komutu, işlem kodunu işlemeden önce kaynak IP, oturum ve bağlantı yük bütçelerinden düşer. Her oturumun kendi oturum bütçesi vardır ve bağlantı kimliği doğrulanmamışken bu bütçe atlanır.

Kayıt dışındaki bir işlem kodu, oturum bağlıysa 4001 koduyla ve Unknown opcode nedeniyle, bağlantı kimliği doğrulanmamışsa 4003 ile kapatır. op içeren ama d içermeyen bir yük de 4001 ile kapatır; bunun istisnası Identify ve Resume'dur, bunlar 4005 ile kapatır.

Heartbeat¶

İşlem kodu 1, istemcinin işlediği son Dispatch sıra numarasını ya da ilk Dispatch'ten önce null taşır.

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

Kimlik doğrulamadan önce Gateway herhangi bir d değerini kabul eder ve işlem kodu 11 gönderir. d anahtarı olmayan bir yük 4001 koduyla ve Unknown opcode nedeniyle kapatır.

Kimlik doğrulandıktan sonra ne null ne de tamsayı olan bir d, 4007 koduyla ve Invalid sequence nedeniyle kapatır. Her tamsayı kabul edilir, ancak onaylar hiçbir zaman geriye gitmez. Onaylanmış en yüksek sıra numarasına eşit veya altındaki Dispatch'ler artık Resume için kullanılamaz.

Oturum sona erdiğinde TEBHOS d: false ile işlem kodu 9 gönderir; bundan sonra heartbeat'ler yeniden onaylanır. Oturumun sona ermesiyle bu çerçeve arasındaki kısa aralıkta gelen bir heartbeat 4007 ile kapatır.

Zamanlama sözleşmesi için bkz. Gateway'e genel bakış.

Identify¶

İşlem kodu 2 kimlik doğrular ve yeni bir oturum oluşturur.

{
  "op": 2,
  "d": {
    "token": "...",
    "properties": {
      "os": "Linux",
      "browser": "my-client",
      "device": "desktop"
    },
    "presence": {
      "status": "online",
      "afk": false,
      "mobile": false
    },
    "ignored_events": ["TYPING_START"],
    "flags": 2,
    "initial_guild_id": "1189375284394692608"
  }
}

token ve properties zorunludur. Bilinmeyen alanlar yok sayılır. intents alanı ve intent sistemi yoktur.

Aşağıdaki hatalar 4002 koduyla ve Invalid identify payload nedeniyle kapatır:

• Eksik token veya properties.
• Nesne olmayan properties.
• os, browser veya device değeri eksik ya da dize olmayan properties.
• Dize dizisi olmayan veya 256'dan fazla girdi içeren bir ignored_events değeri.
• Negatif olmayan bir tamsayı olmayan flags değeri.

Hatalı biçimli bir shard, 4010 koduyla ve Invalid shard nedeniyle kapatır.

shard filtresinden sonra 2.500'den fazla sunucuya çözümlenen bir bot oturumu 4011 koduyla ve Sharding required nedeniyle kapatır. Kullanıcı oturumu sunucu sayısı nedeniyle hiçbir zaman reddedilmez.

API'nin reddettiği bir token 4004 koduyla ve Invalid token nedeniyle kapatır. Kullanıcı oturum token'ı yalnızca giriş oturumu var olduğu sürece kabul edilir; bu yüzden oturumu kapatılmış bir token burada başarısız olur. Zaten 100 canlı oturum tutan bir kullanıcı hesabı 4008 ve Too many sessions nedeniyle kapatır. Bot kimlik bilgisi bu sayıyla sınırlı değildir. Zaten bir oturum bağlı olan bir sokette gönderilen Identify, d içersin veya içermesin 4005 ve Already authenticated nedeniyle kapatır.

API ayrıca her token için oturum başlatmalarını dakikada 20 ile sınırlar. Bu sınırı aşan bir Identify, diğer geçici hatalar gibi tutulur ve sessizce yeniden denenir.

Oturum bayrakları¶

Diğer tüm bitler tanımsızdır. Tanımsız bir bit kabul edilir ve yok sayılır.

DEBOUNCE_MESSAGE_REACTIONS, doğrudan mesajlardaki ve grup doğrudan mesajlarındaki tepkilere uygulanır. Bir sunucu kanalındaki tepki hiçbir zaman birleştirilmez ve kendi Message Reaction Add olayı olarak gelir.

Identify özellikleri nesnesi¶

Yapı¶

os, browser ve device zorunlu dizelerdir. Kalan alanlar isteğe bağlı ipuçlarıdır ve tanınmayan özellikler yok sayılır.

latitude ve longitude, Ready'deki rtc_regions dizisini uzaklığa göre sıralar. Bunları yalnızca dize olarak gönderin: API burada JSON sayısı taşıyan bir oturum isteğini reddeder, Gateway bunu geçici bir hata olarak ele alır ve tutulan Identify'ı yeniden denemeye devam eder; Ready hiç gelmez. Etkili olmaları için ikisinin de gönderilmesi gerekir; sayı olarak ayrıştırılamayan bir dize yokmuş gibi sayılır. Konumu olmayan bir istemci bunları göndermez.

Başlangıç durumu nesnesi¶

Yapı¶

Hesabın kayıtlı durumu şu hâllerde kullanılır: status yoksa veya null ise, unknown dizesiyse ve kayıtlı durum online değilken online ise. Aksi hâlde değer gönderildiği gibi kullanılır.

Identify, offline değerini ayrı bir başlangıç durumu olarak kabul eder; Presence Update ise offline değerini invisible olarak normalleştirir. Çözümlenen durumu offline veya invisible olan bir oturum diğer kullanıcılara status: "offline" ve null bir custom_status yayımlar.

Özel durum nesnesi¶

Yapı¶

Yalnızca bu alanlar okunur. Presence Update nesneyi yayımlamadan önce API üzerinden doğrular: hiçbir emojiyi belirtmeyen bir emoji_id nesneyi reddettirir; TEBHOS Pro'su olmayan bir hesabın emoji_id değeri ise yayımlanan nesneden çıkarılır, geri kalanı korunur. Yayımlanan durum emoji_animated ekler ve emoji_name alanını özel emojinin adıyla doldurur.

Resume¶

İşlem kodu 6, saklanan bir oturumu yeni bir sokette geri yükler.

Tüm alanlar zorunludur. Nesne olmayan bir yük, eksik bir alan, dize olmayan bir token veya session_id ya da tamsayı olmayan bir seq, 4002 koduyla ve Invalid resume payload nedeniyle kapatır.

Bilinmeyen veya süresi dolmuş bir oturum d: false ile işlem kodu 9 üretir ve soketi kimliği doğrulanmamış durumda bırakır. Oturumun sahibi olmayan bir token 4004 ve Invalid token nedeniyle kapatır. Oturumun geçerli sıra numarasının üstündeki ya da zaten onayladığı sıra numarasının altındaki bir seq, 4007 ve Invalid sequence nedeniyle kapatır. Ulaşılamayan bir oturum 4000 ve Session unavailable nedeniyle kapatır. Bu kapanışların hiçbiri, session_id ile belirtilen saklanan oturumu sonlandırmaz.

Başarılı bir Resume, seq değerinin kesinlikle üzerindeki saklanan tüm Dispatch'leri sırasıyla yeniden oynatır ve Resumed ile biter. Ayrıca oturumun soketini değiştirir; yerinden edilen soket işlem kodu 7 alır ve ardından 4000 ile kapanır.

Zaten bir oturum bağlı olan bir sokette gönderilen Resume 4005 koduyla ve Already authenticated nedeniyle kapatır. Resume, kaynak IP'nin Identify bütçesini paylaşır: bütçeyi aşan bir Resume yanıt verilmeden atılır; bu yüzden yeniden bağlanın ve tekrar gönderin.

Presence Update¶

İşlem kodu 3, geçerli oturumun durumunu (presence) değiştirir.

{
  "op": 3,
  "d": {
    "status": "idle",
    "afk": true,
    "mobile": false,
    "custom_status": {
      "text": "away from keyboard"
    }
  }
}

status zorunludur. Nesne olmayan bir yük, status anahtarı olmayan bir nesne ve kabul edilen kümenin dışındaki bir status dizesi; hepsi 4002 koduyla ve Invalid presence payload nedeniyle kapatır. Boş dize online olarak çözümlenir. Bir dize gönderin: dize olmayan değerler reddedilmez, ancak etkileri sözleşmenin parçası değildir.

offline, invisible olarak normalleştirilir; bu yüzden bir Presence Update, bağlıyken bir oturumu çevrimdışı olarak yayımlayamaz.

custom_status yalnızca anahtar mevcutsa değiştirilir. Anahtarı göndermemek geçerli özel durumu korur, null ise temizler. API'nin reddettiği bir nesne (örneğin hiçbir emojiyi belirtmeyen bir emoji_id) geçerli özel durumu yerinde bırakır. Bağlantı açık kalır.

Yayımlanan durum bir özel durum nesnesi taşır ve etkinlik içermez.

Presence Update'in tek bir WebSocket üzerinde 20 saniyede kabul edilen beş komutluk kendi sınırı vardır. Bu aralıktaki sonraki bir güncelleme, paylaşılan yük bütçelerini tükettikten sonra bağlantıyı kapatmadan atılır.

Voice State Update¶

İşlem kodu 4, geçerli Gateway oturumuyla ilişkili ses üyeliğine katılır, onu taşır, günceller veya ondan ayrılır. Yerleşim modelinin tamamı için bkz. Ses.

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

Her alan isteğe bağlıdır, ancak d bir nesne olmalıdır: başka her değer 4002 koduyla ve Invalid voice payload nedeniyle kapatır. Null olmayan bir guild_id veya channel_id ondalık bir snowflake dizesidir. Başka her değer doğrulamadan geçemez ve güncelleme kapanış kodu ve olay olmadan düşürülür.

Komutun session_id alanı yoktur. TEBHOS ses üyeliğini, komutu gönderen Gateway oturumuyla tanımlar.

Bir izne katılmak veya onu değiştirmek, medya bağlantısı için LiveKit token'ı ve uç noktasıyla birlikte Voice Server Update ve kanalı görebilen her oturum için Voice State Update üretir. Reddedilen bir güncelleme hiçbir olay üretmez.

Kayan bir saniyelik penceredeki ilk iki güncelleme hemen etkili olur. Sonraki güncellemeler, aynı guild_id ve connection_id için daha yeni güncellemelerle geciktirilebilir veya değiştirilebilir. Bkz. komut hız sınırları.

Request Guild Members¶

İşlem kodu 8, sınırlı üye parçaları (chunk) ister.

{
  "op": 8,
  "d": {
    "guild_id": "1189375284394692608",
    "query": "ann",
    "limit": 50,
    "presences": true,
    "nonce": "a1b2c3"
  }
}

Komut hiçbir zaman bağlantıyı kapatmaz. Geçersiz girdi dönüştürülür veya atılır:

• Pozitif bir snowflake olmayan bir sunucu kimliği isteğin tamamını iptal eder.
• Yinelenen sunucu kimlikleri birleştirilir.
• 100'den fazla girdi içeren bir user_ids dizisi isteğin tamamını iptal eder. Pozitif snowflake olmayan tek tek girdiler atılır.
• Negatif olmayan bir tamsayı olmayan limit değeri 0 olur, daha büyük bir değer 100 değerine sıkıştırılır.
• Dize olmayan her query boş dize olur.
• En fazla 32 baytlık bir dize olmayan nonce null olur. Nonce yalnızca istek tam olarak bir sunucu belirttiğinde geri yansıtılır.

Oturumun bağlı olmadığı bir sunucu atlanır. Bot bir seferde tek bir sunucu ister; iki veya daha fazla sunucu belirten bir bot isteği iptal edilir.

Boş bir query, 0 değerinde bir limit ve boş bir user_ids birlikte üye listesinin tamamını ister (en fazla 100.000 girdi). Listenin tamamını isteyen bir kullanıcı hesabı o sunucuda MANAGE_ROLES, KICK_MEMBERS ve BAN_MEMBERS izinlerine ihtiyaç duyar; bunlar olmadan yapılan bir istek sessizce düşürülür. Sunucu sahibi ve ADMINISTRATOR iznine sahip üyeler denetimden geçer.

Listenin tamamını isteyen bir bot, her sunucu için 30 saniyede kabul edilen bir istekle sınırlıdır. Bu aralıktaki bir istek Rate Limited üretir ve hiçbir üye parçası üretmez.

Sonuçlar, her biri chunk_index ve chunk_count içeren en fazla 1.000 üyelik sayfalar hâlinde Guild Members Chunk olarak gelir. Bu parçalar canlı olarak teslim edilir ve Resume için hiçbir zaman saklanmaz.

Tek bir WebSocket üzerinde aynı anda yalnızca bir üye isteği çalışır. Biri çalışırken daha yeni bir istek, önceki bekleyen isteğin yerine geçer ve etkin olan bittiğinde başlar. Bu komutun diğer üçüyle paylaştığı dört yuvalık sınırı Sınırlı istekler açıklar.

Lazy Request¶

İşlem kodu 14, oturum için üye listesi, yazıyor bilgisi ve eşitleme trafiğini belirleyen sunucu başına abonelikleri ayarlar.

{
  "op": 14,
  "d": {
    "subscriptions": {
      "1189375284394692608": {
        "active": true,
        "typing": true,
        "member_list_channels": {
          "1189375284394692610": [[0, 99]]
        }
      }
    }
  }
}

Geçerli bir snowflake olmayan bir anahtar, nesne olmayan bir değer ve oturumun bağlı olmadığı bir sunucu, komutun geri kalanını etkilemeden atlanır. Komut hiçbir zaman bağlantıyı kapatmaz.

Sunucu aboneliği nesnesi¶

Yapı¶

TEBHOS her seçeneği yalnızca anahtarı mevcutsa ve active, sync, member_list_channels, members, typing sırasıyla uygular. active ve sync mevcutsa boolean olmalıdır: başka her değer, o sunucu ve henüz işlenmemiş her sunucu için kalan seçeneklerin işlenmesini kapatma olmadan durdurur.

Bir sunucuyu aktif olarak işaretlemek, Olay filtreleme bölümünde belirtildiği gibi ürettiği trafik miktarını değiştirir. Pasiften aktife ve aktiften pasife geçiş, sync olmasa bile ikisi de bir eşitleme anlamına gelir.

member_list_channels, bir kanal kimliğini [start, end] aralıkları listesiyle eşler. Bir aralıkta start en az 0, end en az start, end en fazla 100.000 ve end - start en fazla 99 olmalıdır. Bu sınırlardan geçemeyen aralıklar atılır ve her kanal geçenlerin en fazla ilk 10 tanesini tutar. Birbirinden 100 ms içinde gönderilen abonelikler birleştirilebilir. Oturumun görüntüleyemediği ya da VIEW_CHANNEL_MEMBERS olmadan görüntüleyebildiği bir kanal hiçbir Guild Member List Update almaz. Bir kanala en az bir aralıkla abone olmak, oturumun o sunucudaki diğer üye listesi aboneliklerini düşürür; bu yüzden bir oturum sunucu başına en fazla bir üye listesi tutar.

Snowflake olmayan members girdileri atılır ve geçenlerin ilk 1.000 tanesi tutulur. Oturumun görüntülenebilir hiçbir kanalı paylaşmadığı bir üye de atılır. Her members dizisi, oturumun o sunucu için önceki durum aboneliği kümesinin yerine geçer.

typing, sunucu için Typing Start teslimatına aktif bayrağından bağımsız olarak karar verir. Boolean olmayan değerler yok sayılır.

Request Guild Counts¶

İşlem kodu 15, sunucular için geçerli üye ve çevrimiçi sayılarını ister.

{
  "op": 15,
  "d": {
    "guild_ids": ["1189375284394692608"],
    "nonce": "counts-1"
  }
}

Pozitif snowflake olmayan girdiler atılır ve oturumun bağlı olmadığı bir sunucu atlanır. Uzunluk sınırının dışındaki bir nonce sonuçtan çıkarılır. Komut hiçbir zaman bağlantıyı kapatmaz.

Sonuçlar tek bir Guild Counts Update içinde gelir. İsteğin 3.000 ms'lik bir son süresi vardır ve 2.000 ms içinde yanıt vermeyen bir sunucu çıkarılır.

Request Channel Member Counts¶

İşlem kodu 16, bir sunucudaki kanallar için üye ve çevrimiçi sayılarını ister.

{
  "op": 16,
  "d": {
    "guild_id": "1189375284394692608",
    "channel_ids": ["1189375284394692610"],
    "nonce": "channel-counts-1"
  }
}

Pozitif snowflake olmayan bir guild_id ya da oturumun bağlı olmadığı bir sunucu boş bir sonuç üretir. Pozitif snowflake olmayan kanal girdileri atılır. Komut hiçbir zaman bağlantıyı kapatmaz.

Sonuçlar, 2.000 ms'lik sunucu son süresiyle tek bir Channel Member Counts Update içinde gelir. Bir kanal yalnızca oturum orada hem VIEW_CHANNEL hem de VIEW_CHANNEL_MEMBERS iznine sahipse sayılır.

Sınırlı istekler¶

Tek bir WebSocket; Request Guild Members, Lazy Request, Request Guild Counts ve Request Channel Member Counts genelinde aynı anda en fazla dört sınırlı istek işler. Dört yuvanın tamamı doluyken gelen bir komut, kapatma olmadan ve sonuç üretmeden düşürülür. Her isteğin 10.000 ms'lik bir son süresi vardır; bu süreden sonra başka olay üretmez.

Request Guild Members ayrıca, başka bir üye isteği etkinken değiştirilebilir bir bekleyen istek tutar. Bkz. Sınırlı komutlar.