Chord Geliştirici Dokümantasyonu

Chord Bot API ile kendi botlarını yaz: mesajları canlı dinle, komutlara yanıt ver, sunucularını otomatikleştir. Bu sayfa chord.js kütüphanesini, ham REST API'yi ve gateway olaylarını uçtan uca belgeler.

Nasıl çalışır?

• Uygulama oluşturursun → sana bir bot hesabı ve bir bot tokenı verilir.
• Botunu, sahibi/yöneticisi olduğun sunuculara eklersin.
• Botun REST ile mesaj gönderir/okur, gateway (socket.io) ile mesajları canlı dinler.

Başlangıç

1. Uygulamanı oluştur: Chord'u aç → Ayarlar → Geliştirici Portalı → + Yeni Uygulama. Uygulamana bir ad ver; senin için otomatik bir bot hesabı oluşturulur.
2. Tokenını kaydet: Token yalnızca oluşturma anında bir kez gösterilir. Güvenli bir yere kaydet (kaybedersen portaldan "Tokenı Yenile" ile yenisini üretirsin — eskisi anında geçersiz olur).
3. Botu sunucuna ekle: Uygulama detayında Sunucuya Ekle → sahibi veya yöneticisi olduğun bir sunucuyu seç.
4. İlk isteğini at:

curl https://chord.tr/api/bot/v1/me \
  -H "Authorization: Bot SENIN_TOKENIN"

{ "id": "...", "username": "muzikbotu-bot", "is_bot": true, "application_id": "..." }

Bu yanıtı gördüysen hazırsın — ister chord.js ile ister ham REST ile devam et.

Token güvenliği

• Sunucuda token yalnızca geri döndürülemez özet (sha256) olarak saklanır — biz bile göremeyiz.
• Sızdıysa: Geliştirici Portalı → uygulaman → Tokenı Yenile. Eski token o an ölür.
• Botlar yalnızca /api/bot/* uçlarını çağırabilir — DM, ödeme ve hesap uçları bot tokenlarına kapalıdır.

chord.js — resmî istemci kütüphanesi

discord.js'e aşinaysan evinde hissedeceksin: olay tabanlı Client, msg.reply() gibi kısayollar, otomatik hız-sınırı yönetimi.

Kurulum

1. chord.js dosyasını indir ve projenin klasörüne koy.
2. Canlı olaylar için: npm install socket.io-client (yalnız REST kullanacaksan gerekmez).
3. Node.js 18+ gerekir (yerleşik fetch).

Hızlı başlangıç — ping botu

const { Client } = require('./chord.js');

const client = new Client({ token: process.env.CHORD_TOKEN });

client.on('ready', (me) => {
  console.log(`✅ ${me.username} hazır!`);
});

client.on('message', async (msg) => {
  if (msg.content === '!ping') await msg.reply('Pong! 🏓');
});

client.login();

Client

Olaylar

Message

Channel

Hatalar — ChordAPIError

try {
  await msg.reply('merhaba');
} catch (err) {
  if (err.name === 'ChordAPIError') {
    console.error(err.status, err.path, err.message);  // örn. 403 /v1/channels/... "yetkin yok"
  }
}

REST Referansı

Taban adres: https://chord.tr/api/bot · Kimlik: her istekte Authorization: Bot <token> başlığı · Gövde: Content-Type: application/json.

{ "id", "username", "display_name", "is_bot": true, "application_id", "application_name" }

{ "servers": [ { "id", "name" } ] }

{ "channels": [ { "id", "name", "category" } ] }

{ "message": { "id", "channel_id", "content", "author_id", "author_name", "author_is_bot": 1, "created_at", … } }   // 201

Gateway — canlı olaylar

Gateway, Chord'un socket.io sunucusudur. chord.js bunu senin için yönetir (client.login()); ham kullanım:

const { io } = require('socket.io-client');
const socket = io('https://chord.tr');

socket.on('connect', () => socket.emit('authenticate', 'Bot SENIN_TOKENIN'));
socket.on('authenticated', ({ userId }) => console.log('bağlı:', userId));
socket.on('auth_error', (m) => console.error('kimlik hatası:', m));

socket.on('new_message', ({ message }) => {
  if (message.author_is_bot) return;   // kendi/diğer bot mesajlarını yok say
  console.log(`#${message.channel_id}: ${message.author_name}: ${message.content}`);
});

Önemli davranışlar

• Bot doğrulanınca üye olduğu tüm sunucuların odalarına katılır; kısıtlı kanalların olayları izinsizse gelmez.
• Kendi mesajların da gelir — sonsuz döngüye girmemek için author_id ile filtrele (chord.js bunu otomatik yapar).
• Bağlantı koparsa socket.io kendisi yeniden dener; yeniden bağlandığında authenticate'i tekrar göndermelisin (chord.js otomatik).
• Bot başına tek gateway bağlantısı kur.
• Bot sunucuya eklendiğinde/çıkarıldığında oda üyeliği sunucu tarafından anında güncellenir.

new_message yükü

{ "message": {
  "id", "channel_id", "author_id", "content", "created_at",
  "author_name", "author_display", "author_is_bot",
  "reply_to_id", "attachment_url", "reactions": []
} }

Hız sınırları

chord.js 429 aldığında Retry-After kadar bekleyip isteği kendiliğinden üç kez yineler. Ham REST kullanıyorsan aynısını yapmalısın — 429'u yut, bekle, tekrar dene.

Örnek botlar

1) Komut botu — !ping, !zar, !yardım

const { Client } = require('./chord.js');
const client = new Client({ token: process.env.CHORD_TOKEN });

const komutlar = {
  '!ping':   (msg) => msg.reply('Pong! 🏓'),
  '!zar':    (msg) => msg.reply(`🎲 ${1 + Math.floor(Math.random() * 6)} attın!`),
  '!yardım': (msg) => msg.reply('Komutlar: !ping, !zar, !yardım'),
};

client.on('message', (msg) => komutlar[msg.content]?.(msg));
client.login();

2) Hoş geldin yanıtlayıcısı

client.on('message', async (msg) => {
  if (/^(selam|merhaba|hey)\b/i.test(msg.content)) {
    await msg.reply(`Selam ${msg.author.displayName || msg.author.username}! 👋`);
  }
});

3) Zamanlanmış duyuru (gateway'siz, yalnız REST)

const { Client } = require('./chord.js');
const client = new Client({ token: process.env.CHORD_TOKEN });
const KANAL = 'KANAL_ID';

setInterval(async () => {
  await client.sendMessage(KANAL, '⏰ Saat başı hatırlatma!');
}, 60 * 60 * 1000);

4) Basit denetim — yasaklı kelime

const YASAKLI = ['spam', 'reklam'];

client.on('message', async (msg) => {
  if (YASAKLI.some(k => msg.content.toLowerCase().includes(k))) {
    await msg.reply('⚠️ Lütfen sunucu kurallarına uy.');
  }
});

SSS & sınırlamalar

Botum mesaj atamıyor (403)?

Bot o sunucuda üye mi (portaldan ekledin mi)? Kanalda Mesaj Gönder izni var mı? Botlar sunucuda normal üye rolündedir — kanal izinlerini rol/overwrite'larla yönetebilirsin.

Token'ı kaybettim.

Geliştirici Portalı → uygulaman → Tokenı Yenile. Eski token anında geçersiz olur, botunu yeni token'la yeniden başlat.

Kaç uygulama oluşturabilirim?

Kullanıcı başına 5 aktif uygulama.

v1'de neler yok?

• DM gönderme/okuma (botlar yalnız sunucu kanallarında).
• Mesaj silme/düzenleme, tepki ekleme.
• Slash (/) komutları — yol haritasında.
• Bot mesajları bildirim (mention rozeti) üretmez.

Botu nasıl kaldırırım?

Sunucudan: normal üye gibi at (sağ tık → At). Tamamen: portaldan Uygulamayı Sil — token ölür, bot tüm sunuculardan çıkar; mesaj geçmişi kalır.

Sürüm notları

v1.0 — İlk sürüm: uygulama/token yönetimi, REST v1 (me, servers, channels, messages get/post), gateway new_message, chord.js 1.0.0.