🦝Kanka Chat

Kanka için bot yaz

API sürümü 1 · Kütüphaneler: kanka.js 1.0, kanka.py 1.0
Kısaca:
  • Bot geliştirici başvurun kabul edildiyse Kanka'da Ayarlar › Bot geliştirici sayfası Geliştirici Portalı'na dönüşür. Oradan bot oluşturur, token alırsın.
  • Botunu kendi bilgisayarında ya da sunucunda çalıştırırsın; Kanka'ya WebSocket ile bağlanır, REST API ile mesaj gönderir.
  • /komut, butonlar, seçim menüleri, kartlar ve form pencereleri hazır.
  • Doğrulanmamış bir bot en fazla 50 farklı kişiye ulaşabilir. Büyümek için portaldan doğrulama istersin.
Önce bunu oku:
  • Bot yapmak ücretsiz. Kanka senden hiçbir ücret istemez. Botunu kendi bilgisayarında çalıştırabilirsin; VDS ya da hosting kiralaman gerekmez.
  • 18 yaşından küçüksen bot için para harcamadan önce mutlaka velinle konuş. Geliştirici başvurusunda velinin bilgisi olduğunu onaylarsın.
  • Başkasının botunu kopyalama. Başka bir botun kodunu, adını, logosunu izinsiz kullanmak yasak ve telif hakkı ihlalidir. Açık kaynak kodu lisansına uyarak kullanabilirsin.
  • Botunun yaptığından sen sorumlusun. Bot üzerinden para toplamak, premium satmak ve bahis/çekiliş yasak. Ayrıntılar: Kullanım Şartları, bölüm 6.

1. Beş dakikada ilk bot

  1. Kanka'da Ayarlar › Bot geliştirici › Yeni bot. Bot adını yaz; token bir kez gösterilir, kopyala. İlk botunla birlikte içinde botun hazır olan bir deneme sunucusu açılır.
  2. Kütüphaneyi indir (npm ve PyPI'a yakında):
    ⬇ kanka.js⬇ kanka.py
  3. Token'ı 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();
Token botunun şifresidir. Koda yazma, GitHub'a yükleme. Sızarsa portaldan Token'ı yenile; eskisi anında çalışmaz olur.

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.

2. Komutlar

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
yazimetin (en fazla 1000 karakter)
sayi / tamsayisayı
evethayirtrue / false
kisikullanıcı adı (sunucuda olmalı)
oda / roloda 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}`);
});

3. Butonlar ve seçim menüleri

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 }));

4. Kartlar

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.

5. Form pencereleri

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 }));

6. Olaylar

Bağlanırken hangi olayları istediğini niyetler ile söylersin: new Kanka({ token, niyetler: ['mesajlar', 'uyeler'] }).

NiyetGelen olaylar (kanka.js adı)
mesajlarmesaj, mesajDuzenlendi, mesajSilindi (botun görebildiği odalarda)
icerikYukarıdaki mesajların içeriği. Yoksa içerik sadece bot etiketlendiğinde ya da DM'de gelir.
uyeleruyeKatildi, uyeAyrildi, uyeGuncellendi
tepkilertepki, tepkiKaldirildi
dmBota yazılan özel mesajlar
(her zaman)hazir, sunucuyaEklendi, sunucudanCikarildi, komut ve bileşen etkileşimleri
Doğrulanmamış botlar icerik niyetini serbestçe kullanabilir. Doğrulanan botlar için mesaj içeriği izni doğrulama sırasında ayrıca verilir.

7. REST API

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ç noktaNe yapar
GET /benBotun bilgisi, erişim (kaç kişi), doğrulama durumu
GET /sunucular, GET /sunucular/:idSunucular, 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/mesajlarMesaj gönder: { icerik, kartlar, bilesenler, yanit }
PATCH / DELETE /odalar/:id/mesajlar/:midDüzenle / sil (başkasınınkini silmek için "Mesajları yönet")
PUT / DELETE /odalar/:id/mesajlar/:mid/tepkiler/:emojiTepki ekle / kaldır
PUT / DELETE /odalar/:id/sabitler/:midSabitle / kaldır
POST /kullanicilar/:ad/dmÖzel mesaj (ortak sunucu gerekir)
PUT / DELETE /sunucular/:id/uyeler/:ad/roller/:rolRol 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/:adAt / yasakla
GET / PUT /komutlar, /sunucular/:id/komutlarKomut 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

8. Gateway (kütüphane kullanmayanlar için)

wss://kankahq.com/bot/gateway adresine bağlan. Her mesaj { op, d, t, s } biçiminde JSON'dur.

opAnlamı
10 MERHABASunucu gönderir: { nabizAraligi: 30000 }
2 TANITSen gönderirsin: { token, niyetler: [...] }
1 NABIZ / 11 NABIZ_ALINDIHer nabizAraligi ms'de bir 1 gönder; 75 saniye gelmezse bağlantı kapanır
0 OLAYt: 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 DEVAMKoptuktan 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.

9. HTTP etkileşimleri

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

10. Sınırlar ve kurallar

Sorun mu var? Kanka HQ'daki #bot-gelistirici odasına yaz.