Komutlar

Komut, botunun sunduğu ve kişinin / yazınca listede ya da bir kişiye veya mesaja sağ tıklayınca menüde gördüğü iştir. Bot komutlarını REST ile bir kez kaydeder; kişi bir komutu çalıştırınca botuna bir etkileşim gelir ve ona Etkileşimler sayfasındaki gibi yanıt verirsin.

Kişi ne zaman görür

Kaydettiğin komut sunucuda hemen saklanır ve REST'te hemen görünür. Kişilerin uygulamaları komut listesini en çok 60 saniyede bir yeniler: yeni, değişen ya da silinen komut kişinin ekranına en geç 60 saniyede gelir. Kişiye ayrıca bir olay gitmez.

Bu arada eski tanımla çalıştırılan komut reddedilmez; kişinin uygulaması yeni tanımı alır ve uyan değerleri korur. Yani tanımı değiştirmek için botunu durdurman gerekmez.

Kişi listede yalnızca o kanalda kullanabileceği komutları görür. Kanalda komut kullanma izni (UseApplicationCommands) yoksa ya da kişi zaman aşımındaysa liste boştur. Sunucunun komut izinleri ve komutun default_member_permissions değeri, çalıştırmada olduğu gibi listede de uygulanır: kişinin çalıştıramayacağı komut listede çıkmaz. Sunucu sahibi ve Administrator izni olanlar hepsini görür. Bot sunucudan çıkarılırsa komutları da listeden kalkar, geri eklenince döner. Komutlar sunucunun yazı kanallarında ve kişinin botunla açtığı DM'de listelenir; DM'de hangilerinin çıktığı DM'de komut bölümünde.

Kişi ne görür

Kişi mesaj kutusunun başına / yazınca, imleç ilk kelimedeyken, kutunun üstünde bir liste açılır. Komutlar botlara göre gruplanır: her grubun başında botun avatarı ve adı, altında her komutun adı ve açıklaması durur. Yazdıkça liste daralır; adın başıyla eşleşenler önce gelir. Arama büyük küçük harfe ve i, ı, I, İ farkına bakmaz: /IS yazan kişi /ısınma'yı da görür. Yerelleştirdiğin ad da aranır.

Hiçbir komut eşleşmezse liste hiç çizilmez ve Enter mesajı düz metin olarak gönderir: /home/kero yedek nerede ya da /shrug olduğu gibi gider. Tek başına / yazıp Enter'a basan kişi de düz / gönderir; listeden seçmek için Tab, Enter (en az bir harf yazılmışken) ya da tıklama gerekir. Klavyede ↑ ve ↓ satır değiştirir, Esc listeyi kapatır.

Alt komutu olan komut seçilince liste o komutun satırlarına geçer: /mod kisi ban, /mod at gibi, her biri kendi açıklamasıyla. Grup ve alt komut adları satırda yan yana yazılır.

Komut seçilince mesaj kutusunun yerine bir form gelir. Başında botun avatarı, komutun tam yolu ve açıklaması, sağda kapatma düğmesi durur. Zorunlu seçenekler önce gelir ve adlarının yanında kırmızı bir yıldız vardır. Her seçeneğin altında açıklaması yazar. Seçenek türüne göre denetim:

Kişi Enter'a ya da "Gönder"e basınca uygulama önce zorunlu alanları, uzunlukları, aralıkları ve listeyi denetler; hata alanın altında kırmızı yazar ("Bu alan gerekli", "1 ile 10 arasında olmalı." gibi) ve komut gitmez. Her şey tamsa "Gönder" dönen bir simgeye döner ve bot yanıtlayana kadar bekler. Yanıt gelince form kapanır, mesaj kutusu boşalır. Yanıtın üstünde "{kişi}, /{komut} komutunu kullandı" yazar; type: 5 ile ertelersen botun mesajı düşünüyor hâlini gösterir.

Botun 3 saniye içinde yanıt vermezse ya da çevrimdışıysa form açık kalır ve altında "Bot yanıt vermedi." yazar; kişi yeniden gönderebilir. Sunucudan gelen hata da formun altında görünür, form kapanmaz. Tanımı kişi formu doldururken değiştirirsen kişinin uygulaması yeni tanımı alır, adı ve türü aynı kalan değerleri korur, gideni düşürür ve "Komut güncellendi, kontrol edip yeniden gönder." yazar. Esc ya da kapatma düğmesi formu kapatır ve kişinin yazdığı metin mesaj kutusuna geri gelir.

Kullanıcı ve mesaj menüsü komutların (type: 2 ve 3) sağ tık menüsünde "Uygulamalar" adlı bir alt menüde çıkar: mesaja sağ tıklayınca mesaj komutları, bir kişiye (mesajdaki adına, üye listesinde ya da seste) sağ tıklayınca kullanıcı komutları. Komutlar ada göre sıralanır; birden çok botun komutu varsa her satırın sonunda botun adı yazar. Alt menü yalnızca bir sunucunun yazı kanalında ya da botla açılmış DM'de, o türden en az bir komut varken görünür; ana menü yalnız bir satır uzar, uzun alt menü kayar. Kullanıcı menüsü açık olan kanalda çalışır, bu yüzden yalnız o sunucunun üyesine (DM'de DM'nin kişilerine) sağ tıklayınca çıkar. Menü açılırken ağı beklemez: uygulama listeyi henüz almadıysa onu o an ister ve alt menü bir sonraki sağ tıkta görünür. Komut seçilince hemen çalışır; yanıt kanalda belirir, botun yanıt vermezse ya da bir hata olursa ekranın altında kısa bir uyarı çıkar.

İlk komut: /selam

Uygulama ID'si portalda uygulamanı açınca adres satırının sonunda durur. Bu istek global bir /selam komutu kaydeder:

curl -X POST "https://noluyo.net/api/v1/applications/$APPLICATION_ID/commands" \
  -H "Authorization: Bot $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"selam","description":"Birini selamlar"}'

Yanıt 201 ve komuttur:

{
  "id": "111560000000000000",
  "application_id": "111540000000000000",
  "version": "111560000000000001",
  "guild_id": null,
  "type": 1,
  "name": "selam",
  "name_localizations": null,
  "description": "Birini selamlar",
  "description_localizations": null,
  "options": [],
  "default_member_permissions": null,
  "contexts": [0, 1]
}

Aynı istek ikinci kez 200 döner: aynı türde ve adda komut varsa tanımı değişir, id aynı kalır. version tanım her değiştiğinde değişir.

Global mi, sunucu mu

Geliştirirken sunucu komutu kullan. Yarım kalmış komut yalnızca kendi deneme sunucunda görünür, botunu kullanan diğer sunucular onu görmez. Bitince aynı tanımı global rotaya gönder ve deneme sunucusundakini sil. İkisi aynı adı taşıyabilir: kapsamlar ayrıdır.

Sunucu silinince oradaki komutlar da silinir. Bot sunucudan çıkarılırsa komutları gizlenir ama silinmez; bot geri eklenince döner. Bot üye değilken o sunucunun rotaları 403 döner.

Üç tür

type gönderilmezse 1 sayılır. Tür sonradan değişmez: değiştirmek için komutu silip yeniden oluştur.

Alanlar

Gönderdiğin gövde:

Yanıtta bunlara ek olarak id, application_id, version ve guild_id (global komutta null) gelir. Bilinmeyen alanlar botun isteğinde yok sayılır ve saklanmaz.

Seçenek alanları

Seçenek türleri

Sunucu kişinin gönderdiği değeri tanıma karşı denetler: tür, zorunluluk, choices, aralık ve uzunluk. Seçilen kişi, kanal ya da rolün ayrıntısı etkileşimle birlikte gelir. autocomplete açık seçeneğin değeri bir listeye karşı denetlenmez; onu botun denetlemeli. Ayrıntı Otomatik tamamlama sayfasında. Uzun ya da çok satırlı metin istiyorsan seçenek yerine komuta bir form ile yanıt ver.

Alt komutlar ve gruplar

Bir komut ya düz seçenekler taşır ya da alt komutlar; ikisi aynı seviyede karışmaz. Grup alt komut taşır, alt komut düz seçenek taşır. Daha derin seviye yoktur:

/rol
├── ver      (alt komut: kisi, rol)
├── al       (alt komut: kisi, rol)
└── ayar     (grup)
    ├── goster   (alt komut)
    └── sifirla  (alt komut)

Bu ağacın tanımı:

{
  "name": "rol",
  "description": "Rolleri yönetir",
  "options": [
    { "type": 1, "name": "ver", "description": "Bir kişiye rol verir", "options": [
      { "type": 6, "name": "kisi", "description": "Kime", "required": true },
      { "type": 8, "name": "rol", "description": "Hangi rol", "required": true }
    ] },
    { "type": 1, "name": "al", "description": "Bir kişiden rolü alır", "options": [
      { "type": 6, "name": "kisi", "description": "Kimden", "required": true },
      { "type": 8, "name": "rol", "description": "Hangi rol", "required": true }
    ] },
    { "type": 2, "name": "ayar", "description": "Rol ayarları", "options": [
      { "type": 1, "name": "goster", "description": "Ayarları gösterir" },
      { "type": 1, "name": "sifirla", "description": "Ayarları sıfırlar" }
    ] }
  ]
}

Kişi her çalıştırmada tek bir alt komut seçer. Alt komutlu bir komutun kendisi çalıştırılamaz.

Ad kuralları

• Eğik çizgi komutu ve seçenek adı: harf, rakam, - ve _; en çok 32 karakter; yalnızca küçük harf. Türkçe harfler çalışır: /ısınma, /çekiliş, /iade.

• Büyük harf reddedilir, Türkçe büyük harfler de: /İade ve /Selam 400 validation_failed döner, alan name, kod invalid. /iade ile /ısınma farklı komutlardır; sunucu i ile ı'yı birleştirmez.

• Harfleri birleşik (NFC) biçimde gönder. Bir harfin noktasını ayrı bir işaretle yazan (NFD) metin reddedilir. Çoğu klavye ve dil zaten NFC yazar; emin değilsen name.normalize("NFC") kullan.

• Menü adı (tür 2 ve 3): en çok 32 karakter, büyük harf ve tek boşluk olabilir, başta ve sonda boşluk olamaz: Profili aç.

• Ad, aynı seviyede her dilde tekil olmalı. İki seçeneğin ya da aynı türden iki komutun adı, tr ya da en karşılığı dahil, çakışırsa çakışan invalid alır.

Yerelleştirme

name_localizations ve description_localizations yalnızca tr ve en anahtarlarını alır. Kişi uygulamayı hangi dilde kullanıyorsa o dildeki adı görür; karşılık yoksa name görünür. Botuna her zaman name gelir, dili ne olursa olsun.

{
  "name": "selam",
  "name_localizations": { "en": "hello" },
  "description": "Birini selamlar",
  "description_localizations": { "en": "Greets someone" }
}

Karşılıklar da ad kurallarına uyar. Başka bir dil anahtarı invalid döner.

Toplu güncelleme: PUT

PUT listeyi kapsamın tüm komutları yapar, tek adımda:

curl -X PUT "https://noluyo.net/api/v1/applications/$APPLICATION_ID/commands" \
  -H "Authorization: Bot $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"name":"selam","description":"Birini selamlar"},{"type":2,"name":"Profili aç"}]'

• Türü ve adı eşleşen komutun id'si kalır. Tanımı değişmediyse version'ı da kalır.

• Listede olmayan komut silinir. Boş liste [] hepsini siler.

• Bir tanım geçersizse hiçbir şey değişmez, eski küme yerinde kalır. Hata alanları sırayla işaretlenir: [1].name ikinci komutun adıdır.

• Yanıt 200 ve kapsamın yeni tam listesidir.

Botun her açılışta komutlarını PUT ile göndersin, tek tek POST ile değil. POST silinen komutu silmez, eski bir komut listede kalır; PUT kodundaki listeyi olduğu gibi yazar. Kapsam başına günde 200 yeni komut oluşturulabilir. PUT yalnızca listede yeni olanları sayar; aynı listeyi her açılışta göndermek bu sınırı harcamaz. Her açılışta komutu silip yeniden oluşturan bot ise sınıra çarpar ve 429 alır.

Kim kullanabilir: default_member_permissions

Sunucu kendi kurallarını koyana dek komutu kimin kullanacağını söyler:

Değer, İzinler sayfasındaki bitlerin toplamıdır, ondalık metin olarak. KickMembers (bit 1, 2) ile BanMembers (bit 2, 4) birlikte 2 + 4 = 6 eder. JavaScript'te BigInt ile hesapla:

const kick = 1n << 1n;
const ban = 1n << 2n;
const value = (kick | ban).toString(); // "6"

Bu yalnızca bir varsayılandır, güvenlik değildir. Sunucu yöneticileri izin kurallarıyla komutu başkalarına açabilir ya da kapatabilir. Botun yetki isteyen işte yine kendi denetimini yapmalı.

DM'de komut

Kişi botunla bir DM açarsa (Özel mesajlar) global komutların orada da çalışır: eğik çizgi komutu, kullanıcı menüsü ve mesaj menüsü. Nerede çalışacağını contexts söyler:

contexts gönderilmezse [0, 1] sayılır: komut ikisinde de çalışır. Boş liste, 0 ve 1 dışında bir değer ya da aynı değerin iki kez yazılması validation_failed, contexts: invalid döner. Yanıttaki komut contexts'i her zaman taşır. PATCH ile yalnızca contexts gönderip komutu DM'den çekebilirsin.

Bir komut DM'de ancak üç şart birlikteyse görünür ve çalışır:

Kişinin DM'deki listesinde yalnızca o botun bu şartlara uyan komutları çıkar. İki kişinin DM'sinde ve grup DM'de komut yoktur. Sunucunun komut izinleri DM'de uygulanmaz; DM'de kişiyi durduran onun kapatması ve engelidir.

PUT ile komutun birini yalnız sunucuya, birini yalnız DM'ye ayır:

curl -X PUT "https://noluyo.net/api/v1/applications/$APPLICATION_ID/commands" \
  -H "Authorization: Bot $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"name":"selam","description":"Birini selamlar"},{"name":"ayarlar","description":"Sunucu ayarları","contexts":[0]},{"name":"hatirlat","description":"Sana hatırlatırım","contexts":[1]}]'

DM'den gelen etkileşimde context 1'dir, guild_id ve member yoktur, kişi user içindedir, data.guild_id de yoktur. Kodunu ikisine birden yaz: Sunucuda mı DM'de mi.

Komutu yanıtla

Kişi komutu çalıştırınca botuna INTERACTION_CREATE gelir, type değeri 2'dir. Intent gerekmez; olay sunucunun shard'ına gider. Ona bir butona basma gibi 3 saniye içinde callback ile yanıt verirsin. Gerçek bir çalıştırma şöyle görünür (/zar yuz:20):

{
  "id": "111804206284800120",
  "application_id": "14631410073600008",
  "type": 2,
  "token": "eyJpZCI6IjExMTgwNDIwNjI4NDgwMDEyMCJ9.bWFj",
  "version": 1,
  "guild_id": "21531879014400001",
  "channel_id": "21531887403008007",
  "member": {
    "user": { "id": "14631410073600003", "username": "ayse", "display_name": "Ayşe", "avatar": null, "cosmetics": null },
    "nick": null,
    "roles": [],
    "joined_at": "2026-11-01T10:00:00Z",
    "mute": false,
    "deaf": false,
    "communication_disabled_until": null,
    "permissions": "1071698529857"
  },
  "app_permissions": "1071698529857",
  "locale": "tr",
  "data": {
    "id": "111804206284800050",
    "name": "zar",
    "type": 1,
    "guild_id": "21531879014400001",
    "options": [{ "name": "yuz", "type": 4, "value": 20 }]
  }
}

Sunucu senin yerine şunları denetledi: kişinin bu kanalda komutu kullanabilmesi (UseApplicationCommands, zaman aşımı, komut izinleri, default_member_permissions), seçeneklerin tanıma uyması (tür, zorunlu, seçim listesi, aralık, uzunluk) ve her kullanıcı, rol, kanal ve mesajın kişinin gösterebileceği biri olması. Kullanıcı seçeneği sunucunun üyesidir, rol bu sunucunundur, kanal kişinin gördüğü ve channel_types içindedir. Uymayan çalıştırma kişiye hata döner, sana hiç gelmez. Kişinin uygulaması eski bir tanımla göndermişse sunucu onu reddeder, uygulama yeni tanımı alıp yeniden dener.

Kullanıcı menüsünde target_id kişinin seçtiği üyedir, resolved.users ve resolved.members onu taşır. Mesaj menüsünde target_id bu kanalın mesajıdır ve resolved.messages mesajı içeriğiyle birlikte taşır, botunun MESSAGE_CONTENT intent'i olmasa da. Kişinin o kanalda ReadMessageHistory izni olmalıdır; ephemeral mesaj hedef olamaz.

Yanıt type: 4 ya da type: 5 olur, flags: 64 ile yalnızca çalıştıran kişi görür. Komut çalıştırmanın güncellenecek bir mesajı olmadığı için type: 6 ve type: 7 400 interaction_response_invalid döner. Yanıtın üstünde "Ayşe, /zar kullandı" yazar; mesajın interaction alanı name: "zar" taşır. Takip mesajları ve @original Etkileşimler sayfasındaki gibidir.

Dosya seçeneği

Tür 11 seçenek kişiden komutla birlikte bir dosya ister. Kişi dosyayı seçip komutu çalıştırınca N'oluyo dosyayı saklar ve sana yalnızca bir indirme bağlantısı verir. Seçeneğin value alanı dosyanın kimliğidir, ayrıntısı resolved.attachments içindedir:

"data": {
  "name": "oku",
  "type": 1,
  "options": [{ "name": "dosya", "type": 11, "value": "111804206284800300" }],
  "resolved": {
    "attachments": {
      "111804206284800300": {
        "id": "111804206284800300",
        "filename": "resim.png",
        "content_type": "image/png",
        "size": 5120,
        "width": 640,
        "height": 480,
        "url": "/attachments/21531887403008007/111804206284800300/resim.png?ex=1793000000&sig=..."
      }
    }
  }
}

Kurallar:

• Bağlantı 15 dakika geçerlidir. Sonra 403 link_invalid döner ve dosya kısa süre sonra silinir. Dosyayı o süre içinde indir; saklamak istiyorsan kendi diskinde saklamak senin işin.

• Dosya bir mesaj değildir: kanalda görünmez, kişi de başkası da onu mesaj listesinde bulamaz. Bağlantıyı yalnızca sen alırsın.

• Yanıtında dosyayı göstermek istiyorsan indirip yanıtla birlikte yeniden yükle; bu bağlantıyı mesaja koyma, 15 dakikada ölür.

• Kişi dosyayı kendi yükleme sınırlarıyla yükler: boyut sınırı, saatlik ve günlük yükleme bütçesi ve kanalda AttachFiles izni. Bunlar tutmazsa çalıştırma sana hiç gelmez.

• Bir seviyede en çok 3 dosya seçeneği olur. Zorunlu dosya seçeneği boş kalırsa çalıştırma reddedilir.

Limitler

Yazma rotaları (POST, PUT, PATCH, DELETE) command sınıfındadır: 20 saniyede 5 istek. Okuma read sınıfındadır. Aynı sınırlar openapi.json içinde x-command-limits olarak durur.

Tam örnek: komutları kaydeden betik

Node.js 22 veya üstü yeter, ek paket gerekmez. Betik komut listesini PUT ile gönderir ve kaydedilenleri yazar. GUILD_ID verirsen o sunucuya, vermezsen global kaydeder. Botun her açılışında çalıştırabilirsin:

const API = "https://noluyo.net/api/v1";
const { BOT_TOKEN, APPLICATION_ID, GUILD_ID } = process.env;
if (!BOT_TOKEN || !APPLICATION_ID) throw new Error("BOT_TOKEN ve APPLICATION_ID tanımlı olmalı");

const commands = [
  {
    name: "selam",
    name_localizations: { en: "hello" },
    description: "Birini selamlar",
    description_localizations: { en: "Greets someone" },
    options: [
      { type: 6, name: "kisi", name_localizations: { en: "person" }, description: "Selamlanacak kişi", required: true },
    ],
  },
  { type: 2, name: "Profili aç" },
];

const path = GUILD_ID
  ? `/applications/${APPLICATION_ID}/guilds/${GUILD_ID}/commands`
  : `/applications/${APPLICATION_ID}/commands`;

for (;;) {
  const res = await fetch(API + path, {
    method: "PUT",
    headers: { Authorization: `Bot ${BOT_TOKEN}`, "Content-Type": "application/json" },
    body: JSON.stringify(commands),
  });
  const data = await res.json();
  if (res.status === 429) {
    await new Promise((done) => setTimeout(done, data.retry_after * 1000));
    continue;
  }
  if (!res.ok) throw new Error(`${res.status} ${data.code}: ${JSON.stringify(data.errors ?? data.message)}`);
  for (const c of data) console.log(`${c.name} kaydedildi (${c.id})`);
  break;
}

Çalıştırmak için:

BOT_TOKEN='kopyaladigin_token' APPLICATION_ID='uygulama id degeri' GUILD_ID='deneme sunucusu id degeri' node komutlar.mjs

Tam örnek: /zar botu

Node.js 22 veya üstü yeter. Gateway sayfasındaki gateway.mjs ile Örnekler sayfasındaki api.mjs aynı klasörde olmalı. Bot açılınca /zar komutunu global olarak kaydeder. /zar yuz:20 1 ile 20 arasında bir sayı atar; gizli:true verilirse sonucu yalnızca çalıştıran kişi görür:

import { randomInt } from "node:crypto";
import { connect } from "./gateway.mjs";
import { call } from "./api.mjs";

const commands = [{
  name: "zar",
  name_localizations: { en: "dice" },
  description: "Zar atar",
  description_localizations: { en: "Rolls a die" },
  options: [
    { type: 4, name: "yuz", name_localizations: { en: "sides" }, description: "Kaç yüzlü, yoksa 6",
      description_localizations: { en: "How many sides, 6 if left out" }, min_value: 2, max_value: 100 },
    { type: 5, name: "gizli", name_localizations: { en: "secret" }, description: "Sonucu yalnızca sen gör",
      description_localizations: { en: "Only you see the result" } },
  ],
}];

// Seçenekler tanımdaki adlarıyla gelir: kişi İngilizce kullansa da "yuz", "sides" değil.
const option = (d, name) => d.data.options?.find((o) => o.name === name)?.value;

async function onCommand(d) {
  if (d.type !== 2 || d.data.name !== "zar") return;
  const sides = option(d, "yuz") ?? 6;
  const roll = randomInt(1, sides + 1);
  const content = d.locale === "en" ? `You rolled ${roll} (1-${sides}).` : `${roll} geldi (1-${sides}).`;
  await call("POST", `/interactions/${d.id}/${d.token}/callback`, {
    type: 4,
    data: { content, flags: option(d, "gizli") ? 64 : 0 },
  });
}

let registered = false;

await connect({
  intents: 0,
  onEvent(t, d) {
    if (t === "READY" && !registered) {
      registered = true;
      call("PUT", `/applications/${d.application.id}/commands`, commands)
        .then(() => console.log("/zar kaydedildi"))
        .catch(console.error);
    }
    if (t === "INTERACTION_CREATE") onCommand(d).catch(console.error);
  },
});

Çalıştırmak için:

BOT_TOKEN='kopyaladigin_token' node zar-botu.mjs

Komut kişilerin listesine en geç 60 saniyede gelir. Sunucu yuz'un 2 ile 100 arasında olduğunu zaten denetledi; botun yalnızca seçeneğin hiç gönderilmediği durumu düşünür.

Sık hatalar

Bu sayfayı yapay zekaya verirsen

Sırada ne var

• Komut izinleri: sunucu yöneticilerinin komut erişimini özelleştirmesi

• Otomatik tamamlama: kullanıcı yazarken dinamik seçenek önerileri sunmak

• Formlar: komuta yanıt olarak metin girişli pencere açmak