TAWNY BOT API · v1

Tawny botları için geliştirici dokümanlarıDeveloper documentation for Tawny bots

Tawny Bot API ile sunuculara mesaj gönderen, komutlara cevap veren, yeni üyeleri karşılayan ve tepkilere göre çalışan botlar yazabilirsin. API sade bir REST arayüzü ve uzun yoklamalı (long-poll) bir olay akışından oluşur — WebSocket kütüphanesine gerek yoktur; her programlama dilinde HTTP istekleriyle çalışır.

With the Tawny Bot API you can build bots that send messages to servers, answer commands, greet new members and react to reactions. The API is a simple REST interface plus a long-polling event stream — no WebSocket library required; it works over plain HTTP from any language.

Temel URLBase URL

https://tawny.com.tr/api/v1

Tüm istekler HTTPS üzerinden yapılır, gövdeler application/json biçimindedir. Kimlikler (ID) tam sayıdır; tarihler ISO 8601 (UTC) döner.

All requests use HTTPS and bodies are application/json. IDs are integers; timestamps are ISO 8601 (UTC).

Hızlı başlangıçQuick start

  1. Uygulama oluşturCreate an application

    Geliştirici portalına git, Yeni uygulama de ve botuna bir ad ver. Oluştururken gösterilen tokenı kopyala — yalnız bir kez gösterilir.

    Open the developer portal, click New application and name your bot. Copy the token shown on creation — it is displayed only once.

  2. Botu sunucuna ekleAdd the bot to your server

    Portalın Davet bağlantısı sekmesinde izinleri seç, bağlantıyı aç ve “Sunucuyu Yönet” iznin olan bir sunucu seç.

    In the portal's Invite link tab choose permissions, open the link and pick a server where you have “Manage Server”.

  3. Kodu çalıştırRun the code

    Tokenı TAWNY_TOKEN ortam değişkenine koy ve aşağıdaki örneği çalıştır. Herhangi bir kanala !ping yaz — botun Pong! 🏓 diye cevap verecek.

    Put the token in the TAWNY_TOKEN environment variable and run the sample below. Type !ping in any channel — your bot replies Pong! 🏓.

// Node.js 18+ (yerleşik fetch) — npm paketi gerekmez
const TOKEN = process.env.TAWNY_TOKEN;
const API = 'https://tawny.com.tr/api/v1';
const headers = { Authorization: 'Bot ' + TOKEN, 'Content-Type': 'application/json' };

async function main() {
  let cursor = '';
  for (;;) {
    const res = await fetch(API + '/gateway/events?wait=25&cursor=' + cursor, { headers });
    const data = await res.json();
    cursor = data.cursor;
    for (const ev of data.events) {
      if (ev.type !== 'MESSAGE_CREATE' || ev.data.author.bot) continue;
      if (ev.data.content === '!ping') {
        await fetch(API + '/channels/' + ev.data.channel_id + '/messages', {
          method: 'POST', headers,
          body: JSON.stringify({ content: 'Pong! 🏓' }),
        });
      }
    }
  }
}
main();

Node.js 18 ve üzeri yerleşik fetch içerir; ek paket gerekmez.

Node.js 18+ ships with a built-in fetch; no extra packages are needed.

Kimlik doğrulamaAuthentication

Her istekte Authorization başlığına bot tokenını Bot önekiyle ekle. Token biçimi <bot_id>.<43 karakter> şeklindedir.

Send your bot token in the Authorization header with the Bot prefix on every request. Tokens look like <bot_id>.<43 characters>.

curl https://tawny.com.tr/api/v1/users/@me \
  -H "Authorization: Bot $TAWNY_TOKEN"

Token botunun şifresidir. Asla istemci tarafı koda, ekran görüntülerine veya herkese açık depolara koyma. Sızdığını düşünüyorsan portalda Tokeni yenile ile eskisini anında geçersiz kıl. Tawny tokenları yalnız SHA-256 özeti olarak saklar.

Your token is your bot's password. Never put it in client-side code, screenshots or public repositories. If it leaks, use Reset token in the portal to invalidate the old one instantly. Tawny stores tokens only as SHA-256 hashes.

Botu sunucuya ekleAdding your bot to a server

Davet bağlantısı, botun uygulama kimliğini ve istediği izin değerini taşır:

An invite link carries your application ID and the requested permission integer:

https://tawny.com.tr/app.html?bot_invite={application_id}&permissions={permission_integer}

Bağlantıyı açan kullanıcı, “Sunucuyu Yönet” iznine sahip olduğu sunuculardan birini seçer ve izinleri gözden geçirir. Kullanıcı sahip olmadığı izinleri bota veremez; Yönetici izni yalnız sunucu sahibi ya da yöneticiler tarafından verilebilir. Bot için otomatik olarak, botla aynı adda bir rol oluşturulur.

The user opening the link picks one of the servers where they have “Manage Server” and reviews the permissions. Users can't grant permissions they don't have; Administrator can only be granted by the owner or admins. A role named after the bot is created automatically.

Botun sunucudan ayrılması için DELETE /servers/{id}/members/@me kullanılır; yöneticiler botu normal bir üye gibi atabilir.

Use DELETE /servers/{id}/members/@me to leave a server; admins can kick bots like any member.

Hız sınırlarıRate limits

KapsamScopeSınırLimit
Genel REST istekleriGeneral REST requestsBot başına dakikada 300300 per minute per bot
Mesaj göndermeSending messagesKanal başına 10 saniyede 1010 per 10 seconds per channel
Gateway yoklamasıGateway pollingBot başına dakikada 120120 per minute per bot
Kanal yavaş moduChannel slowmodeKanalın ayarı geçerlidir (BYPASS_SLOWMODE hariç)Channel setting applies (unless BYPASS_SLOWMODE)

Sınır aşılırsa 429 döner; Retry-After başlığı ve gövdedeki retry_after (saniye) kadar bekleyip tekrar dene.

When exceeded you get 429; wait for the Retry-After header / retry_after body field (seconds) and retry.

HatalarErrors

Hatalı istekler uygun HTTP durum koduyla ve aşağıdaki gövdeyle döner:

Failed requests return a suitable HTTP status code and this body:

{
  "code": "missing_permissions",
  "message": "Bu kanala mesaj gönderme izni yok (SEND_MESSAGES)"
}
DurumStatusKodCodeAnlamıMeaning
400invalid_json, invalid_content, invalid_emojiGeçersiz istek gövdesi veya içerikInvalid request body or content
401unauthorizedToken yok, hatalı ya da yenilenmişMissing, invalid or reset token
403missing_permissions, timed_outBotun bu işlem için izni yokThe bot lacks permission for this action
404unknown_server, unknown_channel, unknown_messageKaynak yok ya da bot göremiyorResource missing or not visible to the bot
429rate_limited, slowmodeHız sınırı; retry_after kadar bekleRate limited; wait retry_after seconds
5xxinternal_errorGeçici sunucu hatası; üstel geri çekilmeyle tekrar deneTemporary server error; retry with backoff

İzinlerPermissions

İzinler bit alanıdır; birden fazla izni toplamak için değerleri VEYAla (topla). Botun bir kanaldaki etkin izni; @everyone rolü, botun rolleri ve kanal üzerine yazmalarından hesaplanır.

Permissions are a bit field; combine them with bitwise OR. A bot's effective permission in a channel is computed from @everyone, its roles and channel overwrites.

İzinPermissionDeğerValueAçıklamaDescription
VIEW_CHANNELS4096Kanalı görmeView channels
SEND_MESSAGES16Mesaj göndermeSend messages
READ_MESSAGE_HISTORY1048576Geçmiş mesajları okumaRead message history
ADD_REACTIONS131072Yeni tepki eklemeAdd new reactions
EMBED_LINKS16384GIF/bağlantı yerleştirmeEmbed GIFs/links
ATTACH_FILES8192Dosya eklemeAttach files
MENTION_EVERYONE33554432@everyone / @here bahsetmeMention @everyone / @here
MANAGE_MESSAGES128Başkalarının mesajlarını silmeDelete others' messages
PIN_MESSAGES262144Mesaj sabitlemePin messages
BYPASS_SLOWMODE524288Yavaş modu atlamaBypass slowmode
CREATE_POLLS2097152Anket oluşturmaCreate polls
CREATE_INVITE64Davet oluşturmaCreate invites
KICK_MEMBERS8Üye atmaKick members
BAN_MEMBERS32768Üye yasaklamaBan members
TIMEOUT_MEMBERS65536Zaman aşımıTimeout members
MANAGE_CHANNELS2Kanal yönetimiManage channels
MANAGE_ROLES4Rol yönetimiManage roles
MANAGE_SERVER32Sunucu ayarlarıManage server
CONNECT_VOICE256Sese bağlanmaConnect to voice
SPEAK512Seste konuşmaSpeak in voice
ADMIN1Tüm izinlerAll permissions

Önerilen başlangıç: VIEW_CHANNELS | SEND_MESSAGES | READ_MESSAGE_HISTORY | ADD_REACTIONS | EMBED_LINKS = 1200144

Recommended starting set: VIEW_CHANNELS | SEND_MESSAGES | READ_MESSAGE_HISTORY | ADD_REACTIONS | EMBED_LINKS = 1200144

Mesaj biçimiMessage format

Söz dizimiSyntaxSonuçResult
@kullaniciadiKullanıcıdan bahseder (sunucu üyesiyse)Mentions a user (if they are a member)
<@kullanıcı_id>Kimlikle bahsetme (Discord biçimi) — gönderirken @kullaniciadi olurMention by ID (Discord style) — converted to @username on send
@everyone / @hereHerkesten bahseder — MENTION_EVERYONE gerekirMentions everyone — requires MENTION_EVERYONE
<:ad:id> / <a:ad:id>Sunucu emojisi (durağan / hareketli)Server emoji (static / animated)
:tawny_kalp:Tawny emoji setiTawny emoji set
[gif:https://…]GIF yerleştirme — EMBED_LINKS gerekirGIF embed — requires EMBED_LINKS

Yanıt ve kart için [reply: / [embed: / [cmd: işaretleri elle yazılamaz; reply_to ve embeds alanlarını kullan (aşağıda).

Reply and embed markers ([reply:, [embed:, [cmd:) can't be written by hand; use the reply_to and embeds fields (below).

Mesajlar en fazla 2000 karakterdir. [system: ile başlayan içerik ve dosya belirteçleri ([img:, [vid:, [attachment:) botlar için reddedilir.

Messages are limited to 2000 characters. Content starting with [system: and file tokens ([img:, [vid:, [attachment:) are rejected for bots.

Olay akışı (Gateway)Event stream (Gateway)

GET/gateway/events?cursor={cursor}&wait={seconds}

Gateway, uzun yoklamalı bir uç noktadır: yeni olay yoksa istek en fazla wait saniye (0–25) açık kalır, olay gelir gelmez döner. Her yanıt bir sonraki istekte göndereceğin cursor değerini içerir. İlk istekte imleç göndermezsen geçmiş olmadan bir READY olayı alırsın.

The gateway is a long-polling endpoint: if there are no new events the request stays open for up to wait seconds (0–25) and returns as soon as events arrive. Every response includes the cursor to send with the next request. Without a cursor the first call returns a READY event and no backlog.

{
  "cursor": "1042.388.97.12",
  "events": [
    { "type": "MESSAGE_CREATE", "data": { "id": 1042, "channel_id": 42, "content": "!zar", "author": { "id": 12, "bot": false } } },
    { "type": "MEMBER_JOIN", "data": { "server_id": 7, "user": { "id": 31, "username": "deniz" } } }
  ]
}

Botun gateway'i dinlediği sürece sunucu üye listesinde çevrimiçi görünür. Bağlantı koparsa son imleçle devam et — olaylar kaybolmaz.

While your bot is polling the gateway it appears online in member lists. If the connection drops, resume with your last cursor — events are not lost.

Olay türleriEvent types

OlayEventNe zamanWhendata
READYİlk bağlantı (imleçsiz istek)First connection (request without cursor){ user, servers[] }
MESSAGE_CREATEBotun görebildiği bir kanala mesaj gönderildi. Mesaj botun bir /komutu ise command alanı da gelir.A message was sent in a channel the bot can view. If it invokes one of the bot's /commands a command field is included.Mesaj nesnesiMessage object
MEMBER_JOINSunucuya yeni üye katıldıA new member joined a server{ server_id, user, joined_at }
SERVER_JOINBot bir sunucuya eklendiThe bot was added to a serverSunucu nesnesiServer object
INTERACTION_CREATEBotun mesajındaki düğmeye ya da seçim menüsüne tıklandı (Etkileşimler)A button or select menu on the bot's message was used (Interactions){ id, custom_id, values, user, channel_id, server_id, message }
REACTION_ADDBir mesaja tepki eklendiA reaction was added to a message{ message_id, channel_id, server_id, user_id, emoji }

Botun kendi mesajları da MESSAGE_CREATE olarak gelir; sonsuz döngüye girmemek için author.bot alanını kontrol et.

Your bot's own messages also arrive as MESSAGE_CREATE; check author.bot to avoid infinite loops.

KullanıcılarUsers

GET/users/@me

Botun kendi kullanıcısı ve uygulama bilgisi.

The bot's own user and application info.

GET/users/{user_id}

Botla ortak sunucusu olan bir kullanıcının herkese açık bilgileri. Alanlar: id, username, display_name, avatar, bot.

Public info of a user who shares a server with the bot. Fields: id, username, display_name, avatar, bot.

SunucularServers

GET/servers

Botun bulunduğu sunucular. (/users/@me/servers ile aynı)

Servers the bot is in. (same as /users/@me/servers)

GET/servers/{server_id}

Sunucu ayrıntısı: id, name, icon, banner, description, owner_id, member_count, created_at.

Server details: id, name, icon, banner, description, owner_id, member_count, created_at.

GET/servers/{server_id}/channels

Botun görebildiği kanallar; her kanalda botun etkin permissions değeri bulunur.

Channels visible to the bot; each includes the bot's effective permissions.

GET/servers/{server_id}/roles

Roller (yüksekten alçağa).

Roles (highest first).

GET/servers/{server_id}/members?limit={1-1000}&after={user_id}

Üyeler, kullanıcı kimliğine göre sayfalı. Her üye: user, nickname, roles[], joined_at.

Members paginated by user ID. Each: user, nickname, roles[], joined_at.

GET/servers/{server_id}/members/{user_id}
DELETE/servers/{server_id}/members/@me

Bot sunucudan ayrılır (botun rolü de silinir). Yanıt 204.

The bot leaves the server (its role is removed). Responds 204.

KanallarChannels

GET/channels/{channel_id}

Kanal: id, server_id, name, type (text|voice), topic, category_id, position, slowmode_seconds, permissions.

Channel: id, server_id, name, type (text|voice), topic, category_id, position, slowmode_seconds, permissions.

MesajlarMessages

GET/channels/{channel_id}/messages?limit={1-100}&before={id}&after={id}

Kanal geçmişi, en yeni önce. READ_MESSAGE_HISTORY gerekir.

Channel history, newest first. Requires READ_MESSAGE_HISTORY.

GET/channels/{channel_id}/messages/{message_id}
POST/channels/{channel_id}/messages

Mesaj gönderir. Gövde: { "content": "…", "embeds": [ … ], "reply_to": 1001 } — content ya da en az bir kart gerekli. VIEW_CHANNELS + SEND_MESSAGES gerekir (kart için EMBED_LINKS). Yanıt 201 ve mesaj nesnesi.

Sends a message. Body: { "content": "…", "embeds": [ … ], "reply_to": 1001 } — content or at least one embed is required. Requires VIEW_CHANNELS + SEND_MESSAGES (EMBED_LINKS for embeds). Responds 201 with the message object.

curl -X POST https://tawny.com.tr/api/v1/channels/42/messages \
  -H "Authorization: Bot $TAWNY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Merhaba @ali! 👋"}'
PATCH/channels/{channel_id}/messages/{message_id}

Botun kendi mesajını düzenler: content, embeds, components — verilmeyen alan aynen kalır. Düzenleme herkesin ekranında hemen görünür ("düzenlendi" notuyla).

Edits the bot's own message: content, embeds, components — omitted fields stay. The edit shows up for everyone right away (with an "edited" note).

DELETE/channels/{channel_id}/messages/{message_id}

Botun kendi mesajını ya da MANAGE_MESSAGES ile başkasının mesajını siler. Yanıt 204.

Deletes the bot's own message, or others' with MANAGE_MESSAGES. Responds 204.

Mesaj nesnesiMessage object

{
  "id": 1001,
  "channel_id": 42,
  "server_id": 7,
  "content": "/zar 20",
  "reply_to": null,
  "embeds": [],
  "command": { "name": "zar", "args": { "yüz": 20 }, "raw": "20", "errors": [], "targeted": true },
  "author": { "id": 12, "username": "ali", "display_name": "Ali", "avatar": "uploads/avatars/12.png", "bot": false, "webhook": false },
  "mentions": [],
  "mention_everyone": false,
  "pinned": false,
  "system": false,
  "created_at": "2026-10-03T12:00:00Z"
}

content işaretlerden arındırılmış metindir. reply_to: yanıtlanan mesaj ({ message_id, user_id }), embeds: kartlar, command: yalnız olay akışında ve mesaj bu botun komutuysa.

content is the text without markers. reply_to: the replied message ({ message_id, user_id }), embeds: rich embeds, command: only in the event stream and only when the message is one of this bot's commands.

TepkilerReactions

PUT/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@me
DELETE/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@me

Botun tepkisini ekler/kaldırır; {emoji} URL kodlanmış unicode emoji, :tawny_ad: ya da <:ad:id> olabilir. Mesajda henüz olmayan bir emoji için ADD_REACTIONS gerekir. Yanıt 204.

Adds/removes the bot's reaction; {emoji} is a URL-encoded unicode emoji, :tawny_name: or <:name:id>. Adding an emoji not yet on the message requires ADD_REACTIONS. Responds 204.

# Emoji URL kodlanmalı: 👍 → %F0%9F%91%8D
curl -X PUT https://tawny.com.tr/api/v1/channels/42/messages/1001/reactions/%F0%9F%91%8D/@me \
  -H "Authorization: Bot $TAWNY_TOKEN"

Slash (/) komutlarıSlash (/) commands

Kullanıcı kanalda / yazınca sunucudaki botların komutları açıklamalarıyla listelenir; seçilen komutun seçenekleri kutunun üstünde ipucu olarak görünür (Discord gibi). Komut gönderilince bot olay akışında ayrıştırılmış haliyle alır — metni kendin bölmen gerekmez.

When a user types / in a channel, the commands of the bots in that server are listed with descriptions; the chosen command's options are shown as hints above the input (like Discord). When sent, the bot receives it already parsed in the event stream — no string splitting needed.

PUT/applications/@me/commands

Komut listesini toptan kaydeder (eskilerin yerini alır, boş dizi hepsini siler). En fazla 50 komut, komut başına 10 seçenek. Saatte 20 güncelleme.

Bulk-overwrites the command list (an empty array removes all). Up to 50 commands, 10 options per command. 20 updates per hour.

GET/applications/@me/commands
[
  {
    "name": "zar",
    "description": "Zar at",
    "options": [
      { "name": "yüz", "description": "Kaç yüzlü", "type": "integer" },
      { "name": "renk", "description": "Zar rengi", "type": "string",
        "choices": [ { "name": "Kırmızı", "value": "red" }, { "name": "Mavi", "value": "blue" } ] }
    ]
  },
  { "name": "selam", "description": "Birini selamla",
    "options": [ { "name": "kişi", "type": "user", "required": true }, { "name": "mesaj", "type": "string" } ] }
]
typeKullanıcı yazarUser typesBot alırBot receives
stringmerhaba / "iki kelime"metin — son seçenekse satırın kalanıtext — the rest of the line if it's the last option
integer2020
number2,5 / 2.52.5
booleanevet / hayır / true / falsetrue / false
user@ayse / <@id>{ id, username, display_name, avatar, bot }

Adlar 1-32 küçük harf, rakam, - ya da _ (Türkçe harf olur: /yardım; kullanıcı /yardim yazsa da eşleşir). Zorunlu seçenekler isteğe bağlılardan önce gelir. choices varsa kullanıcı adı ya da değeri yazabilir, bot hep value alır. Eksik ya da hatalı seçenekler command.errors içinde gelir (missing, not_integer, not_number, not_boolean, unknown_user, invalid_choice). Seçiciyle seçilen komut yalnız o bota gider (targeted: true); aynı adlı komutu olan iki bot karışmaz.

Names are 1-32 lowercase letters, digits, - or _ (Unicode letters allowed: /yardım; typing /yardim also matches). Required options come before optional ones. With choices the user may type a name or value; the bot always receives the value. Missing or invalid options arrive in command.errors (missing, not_integer, not_number, not_boolean, unknown_user, invalid_choice). A command chosen from the picker goes only to that bot (targeted: true); two bots with the same command name never collide.

Zengin kartlar (embeds)Rich embeds

Mesaja Discord benzeri kartlar ekle: başlık, açıklama (kalın, italik, kod, bağlantı biçimlendirmesi çalışır), renk şeridi, alanlar, küçük ve büyük görsel, alt bilgi, zaman. Bir mesajda en fazla 5 kart; EMBED_LINKS gerekir.

Attach Discord-style embeds: title, description (bold, italic, code and links work), color bar, fields, thumbnail and image, footer, timestamp. Up to 5 embeds per message; requires EMBED_LINKS.

POST /channels/42/messages
{
  "content": "Haftanın skoru:",
  "embeds": [{
    "title": "🏆 Turnuva sonuçları",
    "url": "https://ornek.com/turnuva",
    "description": "**Ali** bu hafta da birinci!",
    "color": "#22c55e",
    "author": { "name": "Skor Botu", "icon_url": "https://i.imgur.com/logo.png" },
    "fields": [
      { "name": "1.", "value": "Ali — 120", "inline": true },
      { "name": "2.", "value": "Ayşe — 95", "inline": true }
    ],
    "thumbnail": { "url": "https://i.imgur.com/kupa.png" },
    "footer": { "text": "Her pazartesi güncellenir" },
    "timestamp": "2026-10-15T10:00:00Z"
  }]
}
AlanFieldSınırLimit
title / author.name / footer.text256
description2048
fields15 alan; ad 256, değer 102415 fields; name 256, value 1024
color0x22c55e / "#22c55e"
Kart başınaPer embed~6 KB

Görseller (thumbnail, image, ikonlar) yalnız https ve güvenilir görsel sunucularından kabul edilir; diğerleri sessizce çıkarılır (izleyenlerin adresi bilinmeyen sitelere gitmesin): i.imgur.com, media.tenor.com, *.giphy.com, upload.wikimedia.org, avatars.githubusercontent.com, raw.githubusercontent.com, images.unsplash.com, api.dicebear.com, cdn.jsdelivr.net, i.ytimg.com, cdn.discordapp.com, pbs.twimg.com, i.scdn.co, flagcdn.com, ddragon.leagueoflegends.com, Steam CDN, tawny.com.tr. Bağlantılar (url) her https adresi olabilir.

Images (thumbnail, image, icons) are accepted only over https from trusted image hosts; others are silently dropped (so viewers' addresses don't leak to unknown sites): i.imgur.com, media.tenor.com, *.giphy.com, upload.wikimedia.org, avatars.githubusercontent.com, raw.githubusercontent.com, images.unsplash.com, api.dicebear.com, cdn.jsdelivr.net, i.ytimg.com, cdn.discordapp.com, pbs.twimg.com, i.scdn.co, flagcdn.com, ddragon.leagueoflegends.com, Steam CDN, tawny.com.tr. Links (url) may be any https address.

Düğmeler ve seçim menüleriButtons and select menus

Mesaja tıklanabilir bileşenler ekle: components en fazla 5 satırdan (type: 1) oluşur; bir satırda en fazla 5 düğme (type: 2) ya da tek bir seçim menüsü (type: 3) bulunur. Kullanıcı tıklayınca botuna INTERACTION_CREATE olayı gelir. Bileşenler POST /channels/{id}/messages, PATCH /channels/{id}/messages/{id} ve etkileşim yanıtlarında kullanılabilir.

Add clickable components to a message: components holds up to 5 rows (type: 1); each row has up to 5 buttons (type: 2) or a single select menu (type: 3). When someone clicks, your bot receives an INTERACTION_CREATE event. Components work in POST /channels/{id}/messages, PATCH /channels/{id}/messages/{id} and interaction responses.

{
  "content": "Hangi oyunları oynuyorsun?",
  "components": [
    { "type": 1, "components": [
      { "type": 2, "style": "primary", "label": "Katıl", "emoji": "✅", "custom_id": "katil" },
      { "type": 2, "style": "danger", "label": "Ayrıl", "custom_id": "ayril" },
      { "type": 2, "style": "link", "label": "Kurallar", "url": "https://ornek.com/kurallar" }
    ]},
    { "type": 1, "components": [
      { "type": 3, "custom_id": "oyunlar", "placeholder": "Oyunlarını seç",
        "min_values": 1, "max_values": 2,
        "options": [
          { "label": "Valorant", "value": "val", "emoji": "🎯", "description": "Taktiksel FPS" },
          { "label": "Minecraft", "value": "mc", "emoji": "⛏️" }
        ] }
    ]}
  ]
}
AlanFieldAçıklamaDescription
styleprimary (1, mor), secondary (2, gri), success (3, yeşil), danger (4, kırmızı), link (5, bağlantı — custom_id yerine url)primary (1), secondary (2), success (3), danger (4), link (5 — uses url instead of custom_id)
label / emojiEn az biri gerekli; etiket en fazla 80 karakterAt least one is required; label up to 80 characters
custom_id1–100 karakter, mesaj içinde benzersiz; etkileşimde sana geri gelir1–100 characters, unique within the message; sent back with the interaction
disabledSoluk görünür, tıklanamazShown dimmed, can't be clicked
optionsSeçim menüsünde 1–25 seçenek: label (≤100), value (≤100, benzersiz), description, emoji, default1–25 options for a select menu: label (≤100), value (≤100, unique), description, emoji, default
min_values / max_valuesKaç seçenek seçilebilir (0–25, varsayılan 1 / 1). Birden çok seçimde kullanıcı listeden seçip "Gönder"e basarHow many options can be picked (0–25, default 1 / 1). With multiple, users pick and press "Send"

Hatalı yapı 400 invalid_components döner (ör. bir satırda hem düğme hem menü). Bileşenler yalnız bot mesajlarında çizilir.

An invalid layout returns 400 invalid_components (e.g. buttons and a menu in one row). Components are only rendered on bot messages.

EtkileşimlerInteractions

Bir kullanıcı düğmeye bastığında ya da seçim menüsünden seçim yaptığında olay akışına INTERACTION_CREATE gelir. Seçim menüsünde seçilen değerler values dizisindedir.

When someone presses a button or picks from a select menu, the event stream delivers INTERACTION_CREATE. Values picked from a select menu are in values.

{ "type": "INTERACTION_CREATE", "data": {
  "id": 381, "type": 3, "component_type": 2, "custom_id": "katil", "values": [],
  "server_id": 7, "channel_id": 42,
  "user": { "id": 1001, "username": "ali", "display_name": "Ali", "bot": false },
  "message": { "id": 1042, "content": "Hangi oyunları oynuyorsun?", "components": [ … ] }
} }
POST/interactions/{interaction_id}/callback
typeNe yaparWhat it does
7 / "update"Tıklanan mesajı düzenler: data içinde content, embeds, components (verilmeyen alan aynen kalır; components: [] düğmeleri kaldırır)Edits the clicked message: content, embeds, components in data (omitted fields stay; components: [] removes them)
4 / "reply"Kanala, tıklanan mesaja alıntılı yanıt yazarPosts a reply to the clicked message in the channel
6 / "deferred_update"Yalnız onaylar (düğmedeki bekleme işareti kalkar); işi sonra yaparsınJust acknowledges (the button stops spinning); do the work later
curl -X POST https://tawny.com.tr/api/v1/interactions/381/callback \
  -H "Authorization: Bot $TAWNY_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": 7, "data": {"content": "✅ Katıldın!", "components": []}}'

Tıklayan kişi 5 saniye içinde yanıt görmezse "Bot yanıt vermedi" uyarısı çıkar: hemen yanıtla ya da 6 ile onayla. Bir etkileşim bir kez yanıtlanır ve 15 dakika geçerlidir; sonra mesajı PATCH ile düzenleyebilirsin.

If the user sees no response within 5 seconds, they get a "The bot didn't respond" notice: respond right away or acknowledge with 6. An interaction can be answered once and is valid for 15 minutes; after that, edit the message with PATCH.

YanıtlarReplies

Gönderirken reply_to ver: mesaj sohbette alıntılı yanıt olarak görünür (kişinin adı ve mesajın özeti üstte, tıklayınca o mesaja gider). Yanıtlanan mesaj aynı kanalda olmalı, yoksa 404 unknown_message. Gelen mesajlarda reply_to alanı neye yanıt verildiğini söyler.

Pass reply_to when sending: the message is shown as a quoted reply (the author's name and a snippet on top; clicking jumps to it). The replied message must be in the same channel, otherwise 404 unknown_message. Incoming messages carry a reply_to field telling what they reply to.

{ "content": "Pong! 🏓", "reply_to": 1001 }

Bot durumuBot status

PATCH/users/@me

Botun durum yazısını ayarlar; üye listesinde ve profilde görünür. { "status": "/yardım yaz" } — en fazla 128 karakter, null ya da boş metin kaldırır. Dakikada 10 değişiklik.

Sets the bot's status text, shown in member lists and the profile. { "status": "/help to start" } — up to 128 characters, null or empty clears it. 10 changes per minute.

tawny-bot.js

Node.js 18+ için bağımlılıksız resmî kütüphane: olay akışını yeniden bağlanarak dinler, hız sınırında bekleyip tekrar dener, komutları kaydeder, seçenekleri hazır verir, eksik / hatalı kullanımda kullanıcıya örnekli uyarı yazar. Tek dosya — indir, yanına koy.

The official zero-dependency library for Node.js 18+: keeps the event stream alive with reconnects, waits and retries on rate limits, registers your commands, hands you parsed options and replies with a usage hint on missing or invalid input. One file — download and drop it next to your bot.

const { Client, Embed } = require('./tawny-bot');

const bot = new Client({ token: process.env.TAWNY_TOKEN, status: '/zar yaz' });

bot.command({
  name: 'zar',
  description: 'Zar at',
  options: [{ name: 'yüz', description: 'Kaç yüzlü', type: 'integer' }],
}, (ctx) => {
  const n = 1 + Math.floor(Math.random() * (ctx.args['yüz'] || 6));
  return ctx.reply(new Embed().title('🎲 ' + n).color('#818cf8'));
});

bot.on('memberJoin', async (ev) => {
  const ch = await bot.firstTextChannel(ev.server_id);
  if (ch) bot.send(ch.id, `👋 Hoş geldin @${ev.user.username}!`);
});

bot.start();   // komutları kaydeder, olay akışını başlatır
YöntemMethodAçıklamaDescription
bot.command(def, fn)Komut tanımla; ctx.args, ctx.user, ctx.reply(), ctx.react()Define a command; ctx.args, ctx.user, ctx.reply(), ctx.react()
bot.on(olay, fn)ready, message, command, memberJoin, serverJoin, reaction, error
bot.send(kanal, içerik)Metin, Embed ya da { content, embeds, reply_to }Text, an Embed or { content, embeds, reply_to }
bot.reply(mesaj, içerik)Alıntılı yanıtQuoted reply
bot.react / unreact / deleteMessage / getMessagesTepki ve mesaj işlemleriReactions and messages
bot.getServer / getChannels / getMembers / firstTextChannelSunucu bilgileriServer info
bot.setStatus(metin)Bot durumuBot status
new Client({ prefix: "!" })!zar 20 gibi ön ekli kullanım da çalışırPrefixed use like !zar 20 also works

Tam örnek botFull example bot

Komutları (!ping, !zar, !yardim) işleyen, hız sınırlarına uyan ve bağlantı koptuğunda devam eden üretime hazır bir iskelet:

A production-ready skeleton that handles commands (!ping, !zar, !yardim), respects rate limits and resumes after disconnects:

// zar-bot.js — Node.js 18+
const API = 'https://tawny.com.tr/api/v1';
const headers = { Authorization: 'Bot ' + process.env.TAWNY_TOKEN, 'Content-Type': 'application/json' };
const PREFIX = '!';

const api = async (method, path, body) => {
  const res = await fetch(API + path, { method, headers, body: body && JSON.stringify(body) });
  if (res.status === 429) {
    const { retry_after = 5 } = await res.json();
    await new Promise((r) => setTimeout(r, retry_after * 1000));
    return api(method, path, body);
  }
  return res.status === 204 ? null : res.json();
};

const commands = {
  ping: () => 'Pong! 🏓',
  zar: () => '🎲 ' + (1 + Math.floor(Math.random() * 6)),
  yardim: () => 'Komutlar: !ping, !zar, !yardim',
};

async function run() {
  const me = await api('GET', '/users/@me');
  console.log('Bağlandı:', me.username);
  let cursor = '';
  for (;;) {
    try {
      const data = await api('GET', '/gateway/events?wait=25&cursor=' + cursor);
      cursor = data.cursor;
      for (const ev of data.events) {
        if (ev.type === 'MEMBER_JOIN') console.log('Yeni üye:', ev.data.user.username);
        if (ev.type !== 'MESSAGE_CREATE' || ev.data.author.bot) continue;
        const text = ev.data.content.trim();
        if (!text.startsWith(PREFIX)) continue;
        const cmd = commands[text.slice(PREFIX.length).split(/\s+/)[0].toLowerCase()];
        if (cmd) await api('POST', '/channels/' + ev.data.channel_id + '/messages', { content: cmd() });
      }
    } catch (err) {
      console.error(err);
      await new Promise((r) => setTimeout(r, 3000));
    }
  }
}
run();

Botunu 7/24 çalıştırmak için bir VPS, Raspberry Pi ya da süreç yöneticisi (pm2, systemd) kullanabilirsin.

To keep your bot online 24/7, run it on a VPS, a Raspberry Pi or under a process manager (pm2, systemd).

Geliştirici kurallarıDeveloper rules

  • Spam, toplu bahsetme ya da istenmeyen DM yok.
  • Kullanıcı verisini açık izin olmadan saklama veya paylaşma.
  • Taciz, dolandırıcılık, kumar, kara para aklama ve çalıntı kart gibi yasa dışı faaliyetlere aracılık eden botlar kalıcı olarak kapatılır.
  • Tokenını gizli tut; sızan tokenlarla yapılan işlemlerden uygulama sahibi sorumludur.
  • Hız sınırlarını aşmaya çalışma; aşırı yük oluşturan botlar geçici olarak durdurulabilir.
  • No spam, mass mentions or unsolicited DMs.
  • Don't store or share user data without explicit consent.
  • Bots facilitating harassment, scams, gambling, money laundering, stolen cards or other illegal activity are permanently removed.
  • Keep your token secret; the app owner is responsible for actions made with a leaked token.
  • Don't try to evade rate limits; bots causing excessive load may be suspended.

Doğrulanmış bot rozeti için botunu bot dizininde yayınla ve destek üzerinden başvur.

To get the verified bot badge, publish your bot in the directory and apply through support.