Başlarken

Başlangıç: ilk botun

Son güncelleme: 11 Kasım 2026

.md indir Markdown aç .html indirTam PDF

Birkaç dakika sonra sunucunda kendi botun olacak ve ilk mesajını yazmış olacak. Ardından !ping yazılınca yanıt veren küçük bir program yazacağız.

Bunun için bir N'oluyo hesabı, yönettiğin bir sunucu, bir terminal ve curl yeterli. Son adımdaki program için Node.js 22 ya da üstü de gerekir; sürümünü node --version ile görebilirsin. Sözcükler yabancı geliyorsa önce Temel kavramlar sayfasına göz at.

1. Portalı aç

Geliştirici portalına git ve her zamanki gibi N'oluyo hesabınla giriş yap.

2. Uygulamanı oluştur

Yeni uygulama düğmesine bas ve iki şey yaz:

Uygulama adı: Botunun sunucularda görünen adı, en çok 32 karakter.
Bot kullanıcı adı: 4 ile 32 karakter arası; küçük harf, rakam, _ ve . olabilir. Sonradan değiştirilemez.

Sonra Oluştur'a bas.

3. Token'ı kopyala

Karşına botun token'ı çıkar. Kopyala ile alıp güvenli bir yere kaydet, çünkü bir daha gösterilmez. Kaybedersen uygulama sayfasındaki Token'ı yenile ile yenisini alırsın.

Kaydettikten sonra Kopyaladım, devam et'e bas.

4. Botu sunucuna ekle

Uygulama sayfasındaki Ekleme bağlantısı bölümünde bota vereceğin izinleri seç. Bu rehber için üçü yeterli:

Kanalları görüntüle
Mesaj gönder
Mesaj geçmişini oku

Bağlantı izin=68608 ile biter. Bağlantıyı aç'a bas, açılan sayfada Sunucu listesinden sunucunu seç ve Sunucuya ekle'ye bas.

Bot artık sunucunda. Kendi adını taşıyan bir rol de aldı; seçtiğin izinler bu rolde durur.

5. İlk isteğini gönder

Şimdi botu REST ile konuşturacaksın. REST, programının belirli bir adrese HTTP isteği gönderip yanıt aldığı yoldur; bir sayfa açmaya benzer, ama yanıt JSON olarak gelir. Buradan sonra tek ihtiyacın token. Terminalde tanımla:

Bash

export BOT_TOKEN='kopyaladigin_token'

Önce token'ın çalıştığını deneyelim: bu istek botun kendi bilgilerini döndürür. Başlıktaki Bot sözcüğüne dikkat et:

Bash

curl "https://noluyo.net/api/v1/users/@me" \
  -H "Authorization: Bot $BOT_TOKEN"

Botun bulunduğu sunucuları listele ve sunucunun id değerini al. API'de sunucuya guild denir.

Bash

curl "https://noluyo.net/api/v1/users/@me/guilds" \
  -H "Authorization: Bot $BOT_TOKEN"

export GUILD_ID='sunucu id degeri'

Kanalları listele ve "type": 0 olan (metin) bir kanalın id değerini al:

Bash

curl "https://noluyo.net/api/v1/guilds/$GUILD_ID/channels" \
  -H "Authorization: Bot $BOT_TOKEN"

export CHANNEL_ID='kanal id degeri'

Şimdi mesajı gönder:

curl -i -X POST "https://noluyo.net/api/v1/channels/$CHANNEL_ID/messages" \
  -H "Authorization: Bot $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Merhaba, ben yeni botum!"}'

Mesaj kanalda görünür. Yanıt 200 ile mesaj nesnesi olarak gelir. -i sayesinde X-RateLimit-* başlıklarını da görürsün; bunları Hız sınırları sayfasında açıklıyoruz.

6. Biraz daha dene

Önceki yanıttaki id değerini al:

Bash

export MESSAGE_ID='yanittaki id degeri'

Emoji adreste URL kodlanmış olmalıdır. %F0%9F%91%8B, 👋 emojisidir. Portaldaki ekleme bağlantısında Tepki ekle'yi işaretlemediysen tepki izni sunucunun @everyone rolünden gelir; sunucuda kapatılmışsa 403 missing_permissions alırsın.

Bash

# Tepki ver (204)
curl -i -X PUT "https://noluyo.net/api/v1/channels/$CHANNEL_ID/messages/$MESSAGE_ID/reactions/%F0%9F%91%8B/@me" \
  -H "Authorization: Bot $BOT_TOKEN"

# Düzenle (200)
curl -X PATCH "https://noluyo.net/api/v1/channels/$CHANNEL_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bot $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Merhaba, bu mesaj duzenlendi."}'

# Son mesajları oku (200)
curl "https://noluyo.net/api/v1/channels/$CHANNEL_ID/messages?limit=5" \
  -H "Authorization: Bot $BOT_TOKEN"

# Sil (204)
curl -i -X DELETE "https://noluyo.net/api/v1/channels/$CHANNEL_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bot $BOT_TOKEN"

7. Küçük bir bot yaz

Şimdiye kadar her isteği sen gönderdin. Gerçek bir bot ise kanalda olanları duyar ve kendisi yanıt verir. Bunu gateway sağlar: programın N'oluyo'ya bir WebSocket bağlantısı açar, yeni mesajlar bu bağlantıdan anında gelir.

Önce Mesaj içeriği'ni aç. Bot, !ping yazıldığını ancak mesajların metnini okuyabilirse anlar ve bu ayrı bir intent'tir. Intent, botun hangi olayları almak istediğini söylediği seçimdir. Portalda uygulama sayfasına dön, Ayrıcalıklı intent'ler bölümünde Mesaj içeriği'ni aç. Açmazsan program 4014 koduyla kapanır.

Örnek Node.js 22 ya da üstü ister: bu sürümlerde WebSocket hazırdır, ek paket gerekmez. bot.mjs adıyla kaydet:

bot.mjs

const API = "https://noluyo.net/api/v1";
const { BOT_TOKEN } = process.env;
const headers = { Authorization: `Bot ${BOT_TOKEN}`, "Content-Type": "application/json" };

// Sunucu mesajları (1 << 9) ve mesaj içeriği (1 << 15).
const INTENTS = (1 << 9) | (1 << 15);
// Bu kodlarda yeniden bağlanmak işe yarar; diğerlerinde kodu düzeltmek gerekir.
const RETRY = [4000, 4008, 4010];

const res = await fetch(`${API}/gateway/bot`, { headers });
if (!res.ok) throw new Error(`GET /gateway/bot: ${res.status}`);
const { url } = await res.json();

let me;

async function reply(message) {
  const sent = await fetch(`${API}/channels/${message.channel_id}/messages`, {
    method: "POST",
    headers,
    body: JSON.stringify({ content: "pong!", message_reference: { message_id: message.id } }),
  });
  if (!sent.ok) console.error("yanıt gitmedi", sent.status, await sent.text());
}

function connect() {
  const ws = new WebSocket(url);
  let heartbeat;
  let seq = null;
  const send = (op, d) => {
    if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ op, d }));
  };

  ws.onerror = () => {};

  ws.onmessage = (e) => {
    const { op, d, s, t } = JSON.parse(e.data);
    if (s) seq = s;
    if (op === 10) {
      heartbeat = setInterval(() => send(1, seq), d.heartbeat_interval);
      send(2, { token: BOT_TOKEN, intents: INTENTS });
    } else if (t === "READY") {
      me = d.user.id;
      console.log(d.user.username, "bağlandı");
    } else if (t === "MESSAGE_CREATE" && d.author.id !== me && d.content === "!ping") {
      reply(d).catch(console.error);
    }
  };

  ws.onclose = (e) => {
    clearInterval(heartbeat);
    console.error("bağlantı kapandı", e.code, e.reason);
    if (e.code >= 4000 && !RETRY.includes(e.code)) process.exit(1);
    setTimeout(connect, 5000);
  };
}

connect();

Bash

BOT_TOKEN="$BOT_TOKEN" node bot.mjs

Terminalde botun adını görünce kanala !ping yaz, bot yanıt versin.

Bağlantıdan gidip gelen her JSON mesajına çerçeve denir. Çerçevenin op alanındaki sayı, onun ne olduğunu söyler: op 10 sunucunun selamı, op 1 heartbeat, op 2 kendini tanıtma (identify). Kod sırayla şunları yapar:

GET /gateway/bot ile bağlanacağı adresi sorar. Bu adresi koda yazma, buradan öğren.
Bağlantı açılınca gelen op 10 çerçevesindeki aralıkla heartbeat göndermeye başlar. Bu, bağlantının canlı kalmasını sağlar.
op 2 (identify) ile token'ını ve istediği olayları söyler.
READY gelince kendi ID'sini öğrenir. Bot kendi mesajlarını da duyduğu için bu gerekli.
Her MESSAGE_CREATE'te metne bakar, !ping ise REST ile yanıt gönderir. Yanıt için Mesaj geçmişini oku izni gerekir; kanalın mesajlarını duyması için de Kanalları görüntüle.

Bağlantı koparsa bu küçük bot 5 saniye sonra baştan bağlanır ve arada yazılanları kaçırır. Kaçırmamak için oturumu sürdürmek gerekir; Gateway sayfası bunu anlatır ve sonunda hazır bir istemci verir.

REST hâlâ gerekli: gateway yalnızca o andan sonra olanları anlatır ve yalnızca bot dinler. Mesaj göndermek, silmek ve geçmiş mesajları okumak REST işidir. Geçmiş okumalar da aynı içerik kuralına uyar.

Sonraki adım: ilk butonun

Botun mesajına buton da ekleyebilir. Bu istek kanala tek butonlu bir mesaj atar:

Bash

curl -X POST "https://noluyo.net/api/v1/channels/$CHANNEL_ID/messages" \
  -H "Authorization: Bot $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Hazır mısın?","components":[{"type":1,"components":[{"type":2,"style":1,"label":"Hazırım","custom_id":"hazir"}]}]}'

Butona şimdi basarsan birkaç saniye sonra "Bot yanıt vermedi." görürsün: basma botuna INTERACTION_CREATE olarak gider ve bot 3 saniye içinde yanıt vermelidir. Yanıt veren ilk botun için Örnekler sayfasındaki anketle başla. Akışın tamamı Bileşenler, yanıt türleri Etkileşimler, kartlar Embed'ler sayfasında.

Resmi kütüphaneler

Ham HTTP ve WebSocket çerçevelerini kendin yönetmek yerine bağlantı sürdürmeyi (resume), hız sınırı kuyruklarını ve shard aralıklarını senin yerine yöneten resmi paketleri kullanabilirsin:

Node.js 22+ için: JavaScript kütüphanesi
Python 3.11+ için: Python kütüphanesi
Kopyala-çalıştır dokuz örnek: Tarifler

Bu sayfayı yapay zekaya verirsen

Sırada ne var

Gateway: bağlantının tamamı, kopunca sürdürmek, hazır istemci
Ses: ses kanalına girip dosya ya da akış yayınlamak; bot kimseyi duyamaz
Intent'ler: hangi olayları istediğin, mesaj içeriği kuralı
Kimlik doğrulama: token ve istek kuralları
Uygulamalar: portal, bot rolü, herkese açık botlar
İzinler: izin değerleri ve rol sıralaması
Hız sınırları: sınırlar ve 429 yanıtları
Hatalar: tüm hata kodları
Değişiklikler: API'de neler değişti
Örnekler: zamanlı duyuru, sözcük filtresi, butonlu anket ve rol seçici gibi küçük botlar
REST referansı: tüm rotalar; her birinde örnek istek, örnek yanıt ve hata kodları var