Bot yaz

Hızlı başlangıç

1. Bot oluşturMODeep’te Ayarlar → Geliştirici → Bot oluştur. Anahtarı (token) hemen kopyala: bir daha gösterilmez.
2. Sunucuya ekleEkleme bağlantısını kopyala ve aç. Sunucunu seç, istenen yetkileri gör, Ekle. Bot kendi rolüyle katılır.
3. İlk mesajAşağıdaki curl ya da Node örneğini anahtarınla çalıştır. Hazır bir örnek bot: depoda apps/bots/example.

Kimlik doğrulama

Her istek Authorization: Bot <anahtar> başlığını taşır. Adres: https://api.modeep.net/bot/v1. Anahtar 32 rastgele bayttır; MODeep yalnızca özetini saklar ve hiçbir kayda yazmaz. Sızarsa Ayarlar → Geliştirici → Yeni anahtar al: eski anahtar ve bağlantıları anında kapanır. Bot hesapları şifreyle giriş yapamaz, arkadaş eklenemez. Cevaplar her zaman { "ok": true, ... } ya da { "ok": false, "code": "..." } biçimindedir.

curl -X POST https://api.modeep.net/bot/v1/rooms/ODA_ID/messages \
  -H "Authorization: Bot $MODEEP_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba MODeep!"}'

REST uç noktaları

GET /me

Botun kendisi ve eklendiği sunucular.

GET /servers

Eklendiği sunucular (her birinde verilen yetkilerle).

GET /servers/:id

Odalar (yalnızca okuyabildikleri), kategoriler, roller, üye sayısı. E-posta ya da kişisel veri yok.

GET /servers/:id/members

Üyeler: ad, resim, roller (members yetkisiyle).

GET /rooms/:id/messages

Odanın son mesajları; ?before= ile geriye, ?limit= en fazla 60.

POST /rooms/:id/messages

{ text, replyTo?, card? }. Kart: title, description, en fazla 8 fields, rol renklerinden bir color.

PATCH / DELETE /messages/:id

Kendi mesajını düzenler ya da siler (başkasınınkini silmek manageMessages ister).

PUT / DELETE /messages/:id/reactions/:emoji

Tepki ekler ya da kaldırır.

POST /servers/:id/rooms, PATCH /rooms/:id

Oda açar, adını ya da yavaş modunu değiştirir (manageRooms).

POST /servers/:id/members/:userId/kick | ban | mute

Üye atar, yasaklar, susturur ({ "muted": true }); yetkisi ve rolü hedeften yüksekse.

GET / PUT /commands

Botun eğik çizgi komutları (PUT bütün listeyi değiştirir).

POST /interactions/:id/reply

Bir komuta yanıt: { text, card? }.

Gateway: olaylar

Olayları almak için socket.io ile https://api.modeep.net/bot adresine bağlan, auth: { token } ver. Bağlanınca ready gelir (bot, sunucular, son olay numarası). Sonra yalnızca okumaya izni olan olaylar: message.create, message.update, message.delete, reaction.add (okuyabildiği odalarda), member.join, member.leave, voice.join, voice.leave (members yetkisiyle), command.invoke. Her olayın artan bir id’si var: bağlantı koparsa auth: { token, since: sonId } ile yeniden bağlan, son 5 dakikada kaçırdıkların gelir. Botlar kişiler arasındaki özel mesajları, Özel odaları ve okuma izni olmayan odaları asla görmez.

import { io } from 'socket.io-client';

const token = process.env.MODEEP_BOT_TOKEN;
const api = (method, path, body) =>
  fetch('https://api.modeep.net/bot/v1' + path, {
    method,
    headers: { Authorization: 'Bot ' + token, 'Content-Type': 'application/json' },
    body: body && JSON.stringify(body),
  }).then((r) => r.json());

const socket = io('https://api.modeep.net/bot', { auth: { token } });
socket.on('ready', (r) => console.log('hazır:', r.servers.length, 'sunucu'));
socket.on('message.create', async ({ roomId, data }) => {
  if (data.message.text === '!selam' && !data.message.author?.bot) {
    await api('POST', '/rooms/' + roomId + '/messages', { text: 'Selam!', replyTo: data.message.id });
  }
});

Eğik çizgi komutları

Komutlarını PUT /commands ile kaydet: ad (küçük harf), açıklama, isteğe bağlı İngilizce ad ve açıklama, en fazla 5 seçenek (string, int, user, room, bool). Odaya yazma izni olan herkes uygulamada “/” yazınca komutunu bot adınla görür. Gönderilince bota command.invoke gelir (interactionId, seçenekler, gönderen); 3 saniye içinde POST /interactions/:id/reply ile yanıt ver. Daha uzun sürerse odada “düşünüyor…” görünür; yanıtın onun yerine geçer. Yanıt 15 dakika boyunca verilebilir.

PUT /bot/v1/commands
{ "commands": [
  { "name": "zar", "description": "Zar atar", "nameEn": "dice", "descriptionEn": "Rolls a die",
    "options": [{ "name": "yuz", "description": "Kaç yüzlü", "type": "int", "required": false }] }
] }

Yetkiler

• readMessagesErişebildiği odalardaki mesajları okur (olaylar, geçmiş).
• sendMessagesMesaj gönderir, komutlara yanıt verir, tepki ekler.
• commandsEğik çizgi komutları sunar.
• membersÜye ve ses olaylarını alır, üye listesini görür.
• manageMessages, manageRoomsBaşkalarının mesajlarını siler, oda açar ve düzenler.
• kickMembers, banMembers, muteMembers, moveMembersKendi rolünün altındaki üyelere uygular; sunucu sahibine asla.

Sınırlar

• İstekBot başına saniyede 30 istek; fazlası 429 rate_limited.
• MesajBir odada saniyede 5 mesaj. Yavaş mod, otomatik moderasyon ve mesaj uzunluğu (2000) herkes gibi bota da uygulanır.
• Bot sayısıBir hesap en fazla 5 bot oluşturur; bir bot en fazla 25 komut sunar.
• Olay arabelleğiSon 5 dakika ya da 500 olay; daha eskisini geçmişten (GET /rooms/:id/messages) oku.

Kurallar

Botlar Gizlilik metnine ve topluluk kurallarına uyar: istenmeyen mesaj (spam) yok, veri kazıma (scraping) yok, kişilere istenmeden yazmak yok; okuduğun mesajları yalnızca botun işi için ve gerektiği kadar sakla. Bir sunucuya eklenen bot, erişebildiği odaların mesajlarını okuyabilir; botun geliştiricisi bu veriler için ayrı bir veri sorumlusudur. Kurallara uymayan bir bot MODeep ekibi tarafından her yerde kapatılabilir.