/komut, butonlar, seçim menüleri, kartlar ve form pencereleri hazır.KANKA_TOKEN ortam değişkenine koy ve çalıştır. Deneme sunucusunda / yaz; komutun listede.// Node.js 18+ · npm i ws (Node 22'de gerekmez)
const { Kanka } = require('./kanka.js');
const bot = new Kanka({ token: process.env.KANKA_TOKEN });
bot.komut('zar', { aciklama: 'Zar at', secenekler: [{ ad: 'yuz', tur: 'tamsayi', aciklama: 'Kaç yüzlü?' }] },
k => k.cevapla(`🎲 ${1 + Math.floor(Math.random() * k.secenek('yuz', 6))}`));
bot.on('mesaj', m => { if (m.icerik === 'ping') m.cevapla('pong 🏓'); });
bot.on('hazir', () => console.log(bot.ben.ad, 'hazır!'));
bot.baglan();
# Python 3.9+ · pip install aiohttp
import os, random, kanka
bot = kanka.Bot(token=os.environ["KANKA_TOKEN"])
@bot.komut("zar", aciklama="Zar at", secenekler=[kanka.Secenek("yuz", "tamsayi", "Kaç yüzlü?")])
async def zar(k):
await k.cevapla(f"🎲 {random.randint(1, k.secenek('yuz', 6))}")
@bot.olay("mesaj")
async def mesaj(m):
if m["icerik"] == "ping": await m.cevapla("pong 🏓")
bot.calistir()
Botu başka sunuculara eklemek için portaldaki Sunucuya ekleme linkini paylaş: https://kankahq.com/bot-ekle/<uygulama>?izin=manageMessages,kick. Linki açan kişi istenen izinleri görür, onaylar; bot sunucuya kendi rolüyle girer.
Komutlar kullanıcıların / listesinde botun adı ve simgesiyle çıkar. Kanka'nın kendi komutuyla aynı adı taşıyorsa /ad:botadi olarak görünür. Seçenekleri olan bir komutu kullanıcı listeden seçince Kanka seçenekler için bir form açar; /zar 20 ya da /zar yuz:20 gibi yazmak da olur.
| Seçenek türü | Bota gelen değer |
|---|---|
yazi | metin (en fazla 1000 karakter) |
sayi / tamsayi | sayı |
evethayir | true / false |
kisi | kullanıcı adı (sunucuda olmalı) |
oda / rol | oda ya da rol kimliği |
Sabit seçimler için secimler: [{ ad: 'Yazı', deger: 'yazi' }] ekle. Bir komutu tek sunucuya özel yapmak için JavaScript'te { sunucu: '<id>' }, Python'da sunucu="<id>". En fazla 50 komut, komut başına 10 seçenek.
3 saniye kuralı: komuta 3 saniye içinde cevap vermelisin. Uzun sürecek işler için önce k.bekle() de (kullanıcı "düşünüyor…" görür), sonra 15 dakika içinde k.duzenle('...') ile bitir. k.cevapla({ icerik, gizli: true }) cevabı sadece komutu kullanan kişiye gösterir.
bot.komut('rapor', { aciklama: 'Uzun rapor' }, async k => {
await k.bekle();
const sonuc = await uzunIs();
await k.duzenle(`Hazır: ${sonuc}`);
});
Bir mesaja en fazla 5 satır ekleyebilirsin; bir satırda 5 buton ya da 1 seçim menüsü olur. Buton stilleri: ana, ikincil, basari, tehlike, link (link butonu url açar, bota olay gelmez).
const { Kanka, Buton, LinkButon, Secim } = require('./kanka.js');
bot.komut('oylama', { aciklama: 'Hızlı oylama' }, k => k.cevapla({
icerik: 'Akşam oyun var mı?',
bilesenler: [
[Buton('evet', 'Evet', 'basari', { emoji: '👍' }), Buton('hayir', 'Hayır', 'tehlike'), LinkButon('https://kankahq.com', 'Site')],
[Secim('oyun', ['Valorant', 'CS2', 'LoL'], { yerTutucu: 'Hangi oyun?' })],
],
}));
bot.buton(/^(evet|hayir)$/, e => e.guncelle(`${e.kullanici.gorunenAd}: ${e.veri.id}`)); // mesajı yerinde değiştirir
bot.secim('oyun', e => e.cevapla({ icerik: `Seçtiğin: ${e.degerler[0]}`, gizli: true }));
const { Kart } = require('./kanka.js');
k.cevapla({ kartlar: [ new Kart().baslik('Sunucu durumu').aciklama('Her şey yolunda ✅').renk('#2f9e65')
.alan('Üye', '42', true).alan('Çevrimiçi', '17', true).altyazi('Son güncelleme: şimdi') ] });
Kart alanları: baslik, aciklama (markdown), renk, url, alanlar (en fazla 15), resim, kucukResim, altyazi. Resimler https:// olmalı. Mesaj başına 5 kart.
bot.komut('basvur', { aciklama: 'Moderatörlük başvurusu' }, k => k.formAc({
id: 'basvuru', baslik: 'Moderatör başvurusu',
alanlar: [{ id: 'yas', etiket: 'Kaç saat aktifsin?' }, { id: 'neden', etiket: 'Neden sen?', tur: 'uzun' }],
}));
bot.form('basvuru', e => e.cevapla({ icerik: 'Başvurun alındı, teşekkürler!', gizli: true }));
Bağlanırken hangi olayları istediğini niyetler ile söylersin: new Kanka({ token, niyetler: ['mesajlar', 'uyeler'] }).
| Niyet | Gelen olaylar (kanka.js adı) |
|---|---|
mesajlar | mesaj, mesajDuzenlendi, mesajSilindi (botun görebildiği odalarda) |
icerik | Yukarıdaki mesajların içeriği. Yoksa içerik sadece bot etiketlendiğinde ya da DM'de gelir. |
uyeler | uyeKatildi, uyeAyrildi, uyeGuncellendi |
tepkiler | tepki, tepkiKaldirildi |
dm | Bota yazılan özel mesajlar |
| (her zaman) | hazir, sunucuyaEklendi, sunucudanCikarildi, komut ve bileşen etkileşimleri |
icerik niyetini serbestçe kullanabilir. Doğrulanan botlar için mesaj içeriği izni doğrulama sırasında ayrıca verilir.Adres: https://kankahq.com/api/v1 · Başlık: Authorization: Bot <token> · Gövde JSON. Hata olursa { "hata": "..." } döner. Alışık olduğun adlar da kabul edilir: content, embeds, components.
| Uç nokta | Ne yapar |
|---|---|
GET /ben | Botun bilgisi, erişim (kaç kişi), doğrulama durumu |
GET /sunucular, GET /sunucular/:id | Sunucular, odalar, roller, botun izinleri |
GET /sunucular/:id/uyeler[/:ad] | Üyeler |
GET /odalar/:id/mesajlar?limit=50&once=<id> | Mesaj geçmişi |
POST /odalar/:id/mesajlar | Mesaj gönder: { icerik, kartlar, bilesenler, yanit } |
PATCH / DELETE /odalar/:id/mesajlar/:mid | Düzenle / sil (başkasınınkini silmek için "Mesajları yönet") |
PUT / DELETE /odalar/:id/mesajlar/:mid/tepkiler/:emoji | Tepki ekle / kaldır |
PUT / DELETE /odalar/:id/sabitler/:mid | Sabitle / kaldır |
POST /kullanicilar/:ad/dm | Özel mesaj (ortak sunucu gerekir) |
PUT / DELETE /sunucular/:id/uyeler/:ad/roller/:rol | Rol ver / al (botun rolünden aşağıdakiler) |
POST /sunucular/:id/uyeler/:ad/sustur | { dakika, sebep } (0 = kaldır) |
DELETE /sunucular/:id/uyeler/:ad, PUT /sunucular/:id/yasaklar/:ad | At / yasakla |
GET / PUT /komutlar, /sunucular/:id/komutlar | Komut listesini oku / tamamen değiştir |
POST /etkilesim/:id/:token/cevap | { tur: 'mesaj' | 'bekle' | 'guncelle' | 'form', ... } (bot token'ı gerekmez) |
PATCH /etkilesim/:id/:token/mesaj, POST .../takip | "bekle"den sonra düzenle / ek mesaj |
wss://kankahq.com/bot/gateway adresine bağlan. Her mesaj { op, d, t, s } biçiminde JSON'dur.
| op | Anlamı |
|---|---|
| 10 MERHABA | Sunucu gönderir: { nabizAraligi: 30000 } |
| 2 TANIT | Sen gönderirsin: { token, niyetler: [...] } |
| 1 NABIZ / 11 NABIZ_ALINDI | Her nabizAraligi ms'de bir 1 gönder; 75 saniye gelmezse bağlantı kapanır |
| 0 OLAY | t: HAZIR, MESAJ_GELDI, MESAJ_DUZENLENDI, MESAJ_SILINDI, KOMUT, BUTON, SECIM, FORM, UYE_KATILDI, UYE_AYRILDI, UYE_GUNCELLENDI, TEPKI_EKLENDI, TEPKI_KALDIRILDI, SUNUCUYA_EKLENDI, SUNUCUDAN_CIKARILDI; s sıra numarası |
| 6 DEVAM | Koptuktan sonra 2 dakika içinde: { token, oturum, sira }; kaçırdığın olaylar gelir |
Mesajı kim yazdı? Her mesajda yazar alanı vardır: { ad, gorunenAd, bot }. Yazar bir geliştirici botuysa yazar.uygulama da gelir: { id, ad, gorunenAd, dogrulandi, sahip }. Kanka'nın kendi botunun mesajlarında yazar.sistem: true olur. Botların birbirine cevap verip döngüye girmemesi için yazar.bot doğruysa mesajı yok saymanı öneririz.
Kapanış kodları: 4004 token geçersiz, 4005 zaten 2 bağlantı var, 4008 çok sık, 4014 bot durduruldu.
Botun sürekli bağlı kalmak zorunda değil. Portalda bir etkileşim adresi girersen bot bağlı değilken komutlar ve butonlar bu adrese POST edilir; cevabı aynı isteğin cevabında JSON olarak dönersin ({ "tur": "mesaj", "icerik": "..." }). Her istek imzalıdır, mutlaka doğrula:
// X-Kanka-Zaman ve X-Kanka-Imza başlıkları: HMAC-SHA256(sır, zaman + "." + gövde), hex
const { imzaDogrula } = require('./kanka.js');
if (!imzaDogrula(process.env.KANKA_SIR, req.headers['x-kanka-zaman'], hamGovde, req.headers['x-kanka-imza'])) return res.status(401).end();
if (istek.tur === 'PING') return res.json({ tur: 'PONG' }); // adresi kaydederken gelir
429 ve tekrarDene (saniye) döner. Sürekli aşan bot 1 saat durur.Sorun mu var? Kanka HQ'daki #bot-gelistirici odasına yaz.