Temel kavramlar

Bot yazarken karşına önce sekiz sözcük çıkar: uygulama, bot, token, sunucu, kanal, rol, izin ve hız sınırı. Olayları dinlemeye başlayınca üç sözcük daha gelir: gateway, intent ve shard. Mesajına kart ve buton eklediğinde dört sözcük daha: embed, bileşen, etkileşim ve ephemeral mesaj. Bu sayfa her birinin ne olduğunu ve birbirine nasıl bağlandığını anlatır. Daha önce bot yazmadıysan buradan başla.

Kısaca: portalda bir uygulama açarsın, bu sana bir bot hesabı ve bir token verir. Botu bir sunucuya eklersin; orada kendi rolünü alır, rolündeki izinler ise kanallarda neler yapabileceğini belirler. Programın token'la istek gönderir ve hız sınırları içinde kaldığı sürece istediği kadar çalışır.

Uygulama

Uygulama, botunun geliştirici portalındaki kaydıdır: adı, resmi, açıklaması, token'ı ve ekleme bağlantısı burada durur. Her uygulamanın tek bir botu ve tek bir token'ı vardır. Bir hesap en çok 25 uygulamaya sahip olabilir.

Uygulama başlangıçta özeldir, yani botu yalnızca sen ekleyebilirsin. Herkese açık seçeneğini açarsan sunucu yöneten herkes ekleme bağlantısıyla ekleyebilir. Ayrıntılar Uygulamalar ve botlar sayfasında.

Bot

Bot, bir programın kullandığı N'oluyo hesabıdır. Kullanıcı adı ve resmi vardır, üye listesinde ve profilinde BOT etiketi görünür. Sunuculara üye olarak katılır ve izinleri bir üyeninki gibi hesaplanır.

Bir insandan birkaç farkı vardır: kendi başına sunucuya katılamaz, davet kullanamaz, özel mesaj açamaz ve arkadaş ekleyemez. Bir kişi botla DM açabilir; bot orada yazar ama asla ilk o yazmaz. Yaptığı her şey REST referansındaki rotalardan geçer, olup biteni de gateway bağlantısından duyar.

Token

Token, botunun şifresidir. Programın her isteğe şu başlığı ekler ve N'oluyo isteğin hangi bottan geldiğini böyle anlar:

Authorization: Bot <token>

Token yalnızca uygulamayı oluştururken ve yenilerken gösterilir. Onu bilen herkes botun adına iş yapabilir; nasıl saklayacağın Güvenlik sayfasında.

Sunucu (guild)

Sunucu, insanların toplandığı topluluktur: üyeleri, rolleri ve kanalları vardır. API'de sunucunun adı guild'dir; rotalarda /guilds/{guild_id}, yanıtlarda guild_id görürsün.

Bir bot, ancak o sunucuyu yönetme izni (ManageGuild) olan biri ekleme bağlantısını açıp eklerse sunucuya girer. Üyesi olmadığı sunucuları göremez: böyle bir istek 404 unknown_guild döner.

Kanal

Kanal, sunucunun içinde konuşmaların geçtiği yerdir ve kendi ID'si vardır. Mesajlar kanallara gönderilir, bu yüzden mesaj rotaları /channels/{channel_id}/messages biçimindedir. Metin kanallarının type değeri 0'dır; botlar sunucularda yalnızca bunlara mesaj gönderebilir, sesli kanala gönderilen mesaj 400 invalid_channel_type döner. Ses kanallarının type değeri 2'dir; botlar op 4 ile bu kanallara girip ses yayınlayabilir ama kanaldaki kimseyi duyamaz, bkz. Ses.

Kanalların izin ayarları olabilir. Sunucunun genelinde bir iznin olsa bile, kanal o izni senden alabilir.

Rol

Rol, üyelere verilen izin ve rütbe paketidir. Bir üyenin birden çok rolü olabilir. Her sunucuda bir de @everyone rolü vardır ve herkes için geçerlidir.

Bot sunucuya eklenince kendi adını taşıyan bir rol alır. Bu role yönetilen rol denir; botu eklerken seçilen izinler bu rolde durur.

Roller sıralıdır. Üstteki rol alttakini yönetebilir, tersi olmaz. Yeni botun rolü @everyone'ın hemen üstüne konur; bu yüzden bir moderasyon botunun, işlem yapacağı üyelerin rollerinin üstüne taşınması gerekir.

İzin

İzin, tek bir yetkidir: mesaj göndermek (SendMessages), başkasının mesajını silmek (ManageMessages), üye yasaklamak (BanMembers) gibi. Bir rolün izinleri tek bir sayı olarak taşınır ve API bunu metin olarak yazar: "68608".

Botunun bir kanaldaki izinleri üç adımda oluşur:

1. Sunucudaki @everyone rolünün izinleri,

2. bunlara eklenen, botun kendi rollerinin izinleri,

3. kanalın izin ayarlarının bunlardan çıkardıkları ve bunlara ekledikleri.

Gereken izin yoksa istek 403 missing_permissions ile, kanalı görme izni yoksa 403 missing_access ile reddedilir. Hesabın tamamı İzinler sayfasında.

Hız sınırı

Hız sınırı, belirli bir sürede en çok kaç istek gönderebileceğindir. Örneğin bir kanala 5 saniyede en çok 5 mesaj gönderilebilir. Sınırı aşınca 429 yanıtı ve ne kadar beklemen gerektiğini söyleyen bir retry_after değeri gelir. Bekleyip yeniden denersen sorun çıkmaz. Sayılar Hız sınırları sayfasında.

Gateway

REST, programının sorduğunda yanıt alan yoldur. Gateway ise tersi: programının açık tuttuğu bir WebSocket bağlantısıdır ve sunucularda bir şey olduğunda N'oluyo haberi bu bağlantıdan kendisi gönderir. Her habere olay denir: yeni mesaj için MESSAGE_CREATE, katılan üye için GUILD_MEMBER_ADD gibi.

Bot gateway'den duyar, REST ile iş yapar. Ayrıntılar Gateway sayfasında, tüm olaylar Olaylar sayfasında.

Intent

Intent, botun hangi olay gruplarını istediğini söyleyen seçimdir. Yalnızca mesajlarla ilgilenen bir bot, GUILD_MESSAGES ister ve üye olaylarını hiç almaz. Üç intent hassas veri açtığı için ayrıcalıklıdır ve önce portalda açılması gerekir. Bunlardan biri olan MESSAGE_CONTENT olmadan bot, mesajların yazıldığını duyar ama metnini göremez. Ayrıntılar Intent'ler sayfasında.

İzinle karıştırma: izin botun ne yapabileceğini belirler ve sunucu yöneticisi verir. Intent, botun ne duymak istediğini söyler ve sen seçersin.

Shard

Shard, çok büyük bir botun sunucularını birkaç gateway bağlantısına bölmesidir. Küçük bir botun tek bağlantısı olur ve bunu düşünmesi gerekmez. Ayrıntılar Shard'lar sayfasında.

Embed

Embed, botun mesajında metnin altında duran karttır: başlık, açıklama, ad ve değer alanları, renkli bir şerit ve görsel taşır. Mesajın embeds listesinde gider, bir mesajda en çok 10 tane olur. Görseli yalnızca botun aynı mesajla yüklediği bir dosya olabilir. Ayrıntılar Embed'ler sayfasında.

Bileşen

Bileşen, botun mesajına eklediği buton ya da menüdür. Satırlara (type: 1) dizilir; her satır en çok 5 buton ya da tek bir menü taşır. Her bileşenin bir custom_id'si olur, bot basmayı bu değerden tanır. Bağlantı butonu ise yalnızca bir adres açar, bota bir şey göndermez. Ayrıntılar Bileşenler sayfasında.

Etkileşim

Biri butona bastığında ya da menüden seçim yaptığında botuna INTERACTION_CREATE olayı gelir; buna etkileşim denir. Bot 3 saniye içinde yanıt vermelidir: yeni bir mesajla, basılan mesajı güncelleyerek ya da yalnızca "aldım" diyerek. Olayın token'ı 15 dakika boyunca o etkileşimin mesajlarını düzenlemeye ve takip mesajı atmaya yarar. Ayrıntılar Etkileşimler sayfasında.

Etkileşimler gateway yerine botun kendi https adresine de gelebilir; N'oluyo her isteği imzalar, bot yanıtı aynı isteğin cevabında verir. Ayrıntılar HTTP ile teslim sayfasında.

Komut

Komut, botun sunduğu ve kişinin / yazınca listede gördüğü iştir: /selam gibi bir eğik çizgi komutu, ya da bir kişiye veya mesaja sağ tıklayınca çıkan menü satırı. Bot komutlarını REST ile bir kez kaydeder; kişi çalıştırınca botuna bir etkileşim gelir. Komut globaldir ya da tek sunucuya özeldir. Ayrıntılar Komutlar sayfasında.

Ephemeral mesaj

Ephemeral mesaj, bir etkileşime verilen ve yalnızca basan kişinin gördüğü yanıttır (flags: 64). N'oluyo onu saklamaz: kişi sayfayı yenileyince gider, kanalda başka kimse görmez. Dosya taşıyamaz. Ayrıntılar Etkileşimler sayfasında.

Hepsi bir arada: bir isteğin yolculuğu

Programın bir kanala mesaj göndermek istediğinde olanlar şunlar:

1. Program POST /channels/{channel_id}/messages isteğini Authorization: Bot <token> başlığıyla gönderir.

2. N'oluyo token'a bakar. Geçersizse yanıt 401 unauthorized olur.

3. Hız sınırlarına bakar. Aşıldıysa yanıt 429 rate_limited olur.

4. Kanalı bulur. Yoksa veya bot o sunucunun üyesi değilse yanıt 404 unknown_channel olur.

5. Botun bu kanaldaki izinlerini hesaplar. ViewChannel yoksa 403 missing_access, SendMessages yoksa 403 missing_permissions döner.

6. Mesajı kaydeder, kanaldakilere ulaştırır ve 200 ile mesaj nesnesini döndürür.

Bu yolculuğu kendin görmek için Hızlı başlangıç sayfasına geç. Çalışan küçük botlar Örnekler sayfasında.

Sözlük

Bu sayfayı yapay zekaya verirsen

Sırada ne var

• Sözlük: tüm geliştirici terimlerinin iki cümlelik hızlı tanımları

• Hızlı başlangıç: ilk REST isteği ve canlı gateway bağlantısı

• Uygulamalar ve botlar: portal ayarları, bot rolü ve sunucuya ekleme