# 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. > **Mimari özeti (Uygulama -> Bot -> Sunucu):** > 1. **Geliştirici Portalı (`https://noluyo.net/gelistirici/uygulamalar`):** Bir uygulama açtığında bot hesabı, gizli `BOT_TOKEN` ve ekleme bağlantısı üretilir. > 2. **Bot Programın:** `BOT_TOKEN` değerini `.env` dosyasında tutar, canlı olaylar için Gateway WebSocket bağlantısı açar ve `https://noluyo.net/api/v1` adresine `Authorization: Bot ` başlığıyla hız sınırına tabi REST istekleri gönderir. > 3. **Sunucu (`guild`):** Bot ekleme bağlantısıyla sunucuya üye olarak katılır ve kendi rolünü alır; kanal izin ayarları bu rolün izinlerini daraltabilir. 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](https://noluyo.net/gelistirici/uygulamalar) 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](https://noluyo.net/gelistirici/bot-uygulamalari.md) 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](https://noluyo.net/gelistirici/ozel-mesajlar.md); bot orada yazar ama asla ilk o yazmaz. Yaptığı her şey [REST referansındaki](https://noluyo.net/gelistirici/api.md) rotalardan geçer, olup biteni de [gateway](https://noluyo.net/gelistirici/gateway.md) bağlantısından duyar. > **Not:** Bot programın N'oluyo'da çalışmaz. Onu sen kendi bilgisayarında veya kiraladığın bir sunucuda çalıştırırsın. Program durursa bot da durur. ## 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 yalnızca uygulamayı oluştururken ve yenilerken gösterilir. Onu bilen herkes botun adına iş yapabilir; nasıl saklayacağın [Güvenlik](https://noluyo.net/gelistirici/guvenlik.md) 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](https://noluyo.net/gelistirici/ses.md). 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](https://noluyo.net/gelistirici/izinler.md) sayfasında. > **İpucu:** Bota yalnızca gerçekten kullanacağı izinleri ver. Sonradan izin eklemek kolaydır: sunucu yöneticisi botun rolünü düzenleyebilir. ## 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ı](https://noluyo.net/gelistirici/rate-limit.md) 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](https://noluyo.net/gelistirici/gateway.md) sayfasında, tüm olaylar [Olaylar](https://noluyo.net/gelistirici/olaylar.md) 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](https://noluyo.net/gelistirici/intentler.md) 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](https://noluyo.net/gelistirici/shardlar.md) 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](https://noluyo.net/gelistirici/embedler.md) 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](https://noluyo.net/gelistirici/bilesenler.md) 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](https://noluyo.net/gelistirici/etkilesimler.md) 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](https://noluyo.net/gelistirici/http-teslim.md) 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](https://noluyo.net/gelistirici/komutlar.md) 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](https://noluyo.net/gelistirici/etkilesimler.md#yalnizca-basan-kisi-gorsun) 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 ` 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ıç](https://noluyo.net/gelistirici/baslangic.md) sayfasına geç. Çalışan küçük botlar [Örnekler](https://noluyo.net/gelistirici/ornekler.md) sayfasında. ## Sözlük | Burada | API'de | Anlamı | |---|---|---| | Uygulama | `application` | Botun portaldaki kaydı | | Bot | `bot`, `user` | Programın kullandığı hesap | | Token | `Authorization: Bot` | Botun şifresi | | Sunucu | `guild` | Topluluk | | Kanal | `channel` | Konuşmaların geçtiği yer | | Üye | `member` | Bir sunucudaki kullanıcı veya bot | | Rol | `role` | İzin ve rütbe paketi | | Yönetilen rol | `application_id` dolu rol | Bota ait rol | | İzin ayarı | `permission_overwrites` | Kanalın izinleri değiştirmesi | | Hız sınırı | `X-RateLimit-*`, `429` | İstek sayısının üst sınırı | | Gateway | `GET /gateway/bot`, WebSocket | Olayların geldiği açık bağlantı | | Olay | `op 0`, `t` alanı | Gateway'den gelen tek bir haber | | Intent | identify'da `intents` | Botun istediği olay grupları | | Shard | identify'da `shard` | Botun sunucularını bölen bağlantı | | Oturum | `session_id` | Bir identify ile başlayan, kopunca sürdürülebilen bağlantı durumu | | Embed | `embeds` | Mesajdaki kart | | Bileşen | `components` | Mesajdaki buton ya da menü | | Etkileşim | `INTERACTION_CREATE` | Bir basma ve botun ona yanıtı | | Ephemeral mesaj | `flags: 64` | Yalnızca basan kişinin gördüğü yanıt | | Komut | `/applications/{id}/commands` | Botun `/` listesinde ya da sağ tık menüsünde sunduğu iş | ## Bu sayfayı yapay zekaya verirsen > **İpucu:** Yapay zekaya N'oluyo terimlerini tanıtırken snowflake kimliklerinin 64 bitlik sayısal dizgiler (`string`) olarak taşındığını, `parseInt` veya `Number` ile yuvarlanmaması gerektiğini ve botların ses kanallarında yalnızca yayın yapabildiğini belirt. ## Sırada ne var - [Sözlük](https://noluyo.net/gelistirici/sozluk.md): tüm geliştirici terimlerinin iki cümlelik hızlı tanımları - [Hızlı başlangıç](https://noluyo.net/gelistirici/baslangic.md): ilk REST isteği ve canlı gateway bağlantısı - [Uygulamalar ve botlar](https://noluyo.net/gelistirici/bot-uygulamalari.md): portal ayarları, bot rolü ve sunucuya ekleme