MicupBETA
UygulamaGiriş Yap

Geliştirici Botu API

v1 · kapsamlı sunucu uygulamasıUygulama dizini

BAŞLANGIÇ

Bir bot, bir kurulum, açık kanal izinleri

Sunucu yöneticisi dizinden Geliştirici Botu kurar. Jeton yalnız bir kez gösterilir; sunucu tarafında yalnız SHA-256 özeti tutulur. Jetonu URL'ye koyma, kayda yazma veya tarayıcıya gönderme. İnsan oturumu Bearer, bot kimliği daima Bot şeması kullanır.

Kimliği doğrula

curl -sS 'https://<micup-host>/api/bot/v1/me' \
  -H 'Authorization: Bot <BOT_TOKEN>'

Yanıt yalnız uygulama adı, sunucu kimliği, izinli kanallar/kapsamlar, jeton sürümü ve bitişini içerir.

Mesaj gönder

curl -sS -X POST 'https://<micup-host>/api/bot/v1/messages' \
  -H 'Authorization: Bot <BOT_TOKEN>' \
  -H 'Content-Type: application/json' \
  --data '{"channelId":"<CHANNEL_UUID>","content":"Maç 20:00’de başlıyor."}'

Gereken kapsam: messages.write. İçerik 1–2.000 karakterdir. Bot mesajlarında hiçbir @ etiketi kabul edilmez. Botlar yanıt hedefi gönderemez; etiket, yanıt ve anahtar kelime bildirimi üretmez. Mesajlar ayrı uygulama kimliğiyle yazılır; yavaş mod, engelli bağlantı ve uygulama moderasyonu yeniden denetlenir.

Kanal olaylarını sırayla oku

curl -sS 'https://<micup-host>/api/bot/v1/events?cursor=<CURSOR>&limit=50' \
  -H 'Authorization: Bot <BOT_TOKEN>'

Gereken kapsam: messages.read. Yalnız özel olarak izin verilen kanalların yeni mesaj olayları gelir. Sayfa 1–100, kurulum başına kuyruk 1.000 olaydır. Olay okunurken mesajın güncel içeriği ve kanal izni denetlenir; önceki metin gönderilmez, silinen mesaj atlanır. Boş bir sayfada da ilerleyebilen nextCursor değerini bir sonraki istekte kullan; 2 saniyeden sık sorgulama. Daha önce botun aldığı içeriği dış sistemden geri çekemeyiz.

Hata ve yaşam döngüsü

  • 401 invalid_bot_token: jeton yanlış, süresi dolmuş veya yenilenmiş.
  • 403 channel_not_allowed: kanal/kapsam kaldırılmış ya da kurulum iptal edilmiş.
  • 429 rate_limited: Retry-After kadar bekle.

Yönetici kapsamı değiştirdiğinde sonraki eylem bunu hemen görür. Jeton yenileme eski jetonu, kaldırma bütün erişimi anında keser.

Yerel örnek

Depodaki examples/micup-bot.mjs yalnız MICUP_BOT_TOKEN, MICUP_BASE_URL ve isteğe bağlı MICUP_CHANNEL_ID ortam değişkenlerini okur. Ek paket veya saklı sır gerekmez.

MICUP_BASE_URL='http://localhost:3000' \
MICUP_BOT_TOKEN='<BOT_TOKEN>' \
MICUP_CHANNEL_ID='<CHANNEL_UUID>' \
node examples/micup-bot.mjs