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
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
- 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.
- 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”.
- Kodu çalıştırRun the code
Tokenı
TAWNY_TOKENortam değişkenine koy ve aşağıdaki örneği çalıştır. Herhangi bir kanala!pingyaz — botunPong! 🏓diye cevap verecek.Put the token in the
TAWNY_TOKENenvironment variable and run the sample below. Type!pingin any channel — your bot repliesPong! 🏓.
// 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();# Python 3.8+ — pip install requests
import os, requests
API = "https://tawny.com.tr/api/v1"
H = {"Authorization": "Bot " + os.environ["TAWNY_TOKEN"]}
cursor = ""
while True:
r = requests.get(API + "/gateway/events", params={"wait": 25, "cursor": cursor}, headers=H, timeout=40).json()
cursor = r["cursor"]
for ev in r["events"]:
msg = ev["data"]
if ev["type"] == "MESSAGE_CREATE" and not msg["author"]["bot"] and msg["content"] == "!ping":
requests.post(API + "/channels/" + str(msg["channel_id"]) + "/messages",
json={"content": "Pong! 🏓"}, headers=H)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"const res = await fetch('https://tawny.com.tr/api/v1/users/@me', {
headers: { Authorization: 'Bot ' + process.env.TAWNY_TOKEN },
});
console.log(await res.json());import os, requests
r = requests.get("https://tawny.com.tr/api/v1/users/@me",
headers={"Authorization": "Bot " + os.environ["TAWNY_TOKEN"]})
print(r.json())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:
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
| KapsamScope | SınırLimit |
|---|---|
| Genel REST istekleriGeneral REST requests | Bot başına dakikada 300300 per minute per bot |
| Mesaj göndermeSending messages | Kanal başına 10 saniyede 1010 per 10 seconds per channel |
| Gateway yoklamasıGateway polling | Bot başına dakikada 120120 per minute per bot |
| Kanal yavaş moduChannel slowmode | Kanalı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)"
}| DurumStatus | KodCode | AnlamıMeaning |
|---|---|---|
| 400 | invalid_json, invalid_content, invalid_emoji | Geçersiz istek gövdesi veya içerikInvalid request body or content |
| 401 | unauthorized | Token yok, hatalı ya da yenilenmişMissing, invalid or reset token |
| 403 | missing_permissions, timed_out | Botun bu işlem için izni yokThe bot lacks permission for this action |
| 404 | unknown_server, unknown_channel, unknown_message | Kaynak yok ya da bot göremiyorResource missing or not visible to the bot |
| 429 | rate_limited, slowmode | Hız sınırı; retry_after kadar bekleRate limited; wait retry_after seconds |
| 5xx | internal_error | Geç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.
| İzinPermission | DeğerValue | AçıklamaDescription |
|---|---|---|
VIEW_CHANNELS | 4096 | Kanalı görmeView channels |
SEND_MESSAGES | 16 | Mesaj göndermeSend messages |
READ_MESSAGE_HISTORY | 1048576 | Geçmiş mesajları okumaRead message history |
ADD_REACTIONS | 131072 | Yeni tepki eklemeAdd new reactions |
EMBED_LINKS | 16384 | GIF/bağlantı yerleştirmeEmbed GIFs/links |
ATTACH_FILES | 8192 | Dosya eklemeAttach files |
MENTION_EVERYONE | 33554432 | @everyone / @here bahsetmeMention @everyone / @here |
MANAGE_MESSAGES | 128 | Başkalarının mesajlarını silmeDelete others' messages |
PIN_MESSAGES | 262144 | Mesaj sabitlemePin messages |
BYPASS_SLOWMODE | 524288 | Yavaş modu atlamaBypass slowmode |
CREATE_POLLS | 2097152 | Anket oluşturmaCreate polls |
CREATE_INVITE | 64 | Davet oluşturmaCreate invites |
KICK_MEMBERS | 8 | Üye atmaKick members |
BAN_MEMBERS | 32768 | Üye yasaklamaBan members |
TIMEOUT_MEMBERS | 65536 | Zaman aşımıTimeout members |
MANAGE_CHANNELS | 2 | Kanal yönetimiManage channels |
MANAGE_ROLES | 4 | Rol yönetimiManage roles |
MANAGE_SERVER | 32 | Sunucu ayarlarıManage server |
CONNECT_VOICE | 256 | Sese bağlanmaConnect to voice |
SPEAK | 512 | Seste konuşmaSpeak in voice |
ADMIN | 1 | Tü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 dizimiSyntax | SonuçResult |
|---|---|
@kullaniciadi | Kullanı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 / @here | Herkesten 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)
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
| OlayEvent | Ne zamanWhen | data |
|---|---|---|
READY | İlk bağlantı (imleçsiz istek)First connection (request without cursor) | { user, servers[] } |
MESSAGE_CREATE | Botun 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_JOIN | Sunucuya yeni üye katıldıA new member joined a server | { server_id, user, joined_at } |
SERVER_JOIN | Bot bir sunucuya eklendiThe bot was added to a server | Sunucu nesnesiServer object |
INTERACTION_CREATE | Botun 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_ADD | Bir 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
Botun kendi kullanıcısı ve uygulama bilgisi.
The bot's own user and application info.
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
Botun bulunduğu sunucular. (/users/@me/servers ile aynı)
Servers the bot is in. (same as /users/@me/servers)
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.
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.
Roller (yüksekten alçağa).
Roles (highest first).
Ü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.
Bot sunucudan ayrılır (botun rolü de silinir). Yanıt 204.
The bot leaves the server (its role is removed). Responds 204.
KanallarChannels
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
Kanal geçmişi, en yeni önce. READ_MESSAGE_HISTORY gerekir.
Channel history, newest first. Requires READ_MESSAGE_HISTORY.
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! 👋"}'await fetch('https://tawny.com.tr/api/v1/channels/42/messages', {
method: 'POST',
headers: { Authorization: 'Bot ' + TOKEN, 'Content-Type': 'application/json' },
body: JSON.stringify({ content: 'Merhaba @ali! 👋' }),
});requests.post("https://tawny.com.tr/api/v1/channels/42/messages",
json={"content": "Merhaba @ali! 👋"}, headers=H)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).
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
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"const emoji = encodeURIComponent('👍');
await fetch(API + '/channels/42/messages/1001/reactions/' + emoji + '/@me', { method: 'PUT', headers });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.
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.
[
{
"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" } ] }
]| type | Kullanıcı yazarUser types | Bot alırBot receives |
|---|---|---|
string | merhaba / "iki kelime" | metin — son seçenekse satırın kalanıtext — the rest of the line if it's the last option |
integer | 20 | 20 |
number | 2,5 / 2.5 | 2.5 |
boolean | evet / hayır / true / false | true / 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"
}]
}| AlanField | SınırLimit |
|---|---|
title / author.name / footer.text | 256 |
description | 2048 |
fields | 15 alan; ad 256, değer 102415 fields; name 256, value 1024 |
color | 0x22c55e / "#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": "⛏️" }
] }
]}
]
}| AlanField | AçıklamaDescription |
|---|---|
style | primary (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 / emoji | En az biri gerekli; etiket en fazla 80 karakterAt least one is required; label up to 80 characters |
custom_id | 1–100 karakter, mesaj içinde benzersiz; etkileşimde sana geri gelir1–100 characters, unique within the message; sent back with the interaction |
disabled | Soluk görünür, tıklanamazShown dimmed, can't be clicked |
options | Seç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_values | Kaç 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": [ … ] }
} }| type | Ne 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": []}}'const { Client, ActionRow, Button, SelectMenu } = require('./tawny-bot');
const bot = new Client({ token: process.env.TAWNY_TOKEN });
bot.command({ name: 'panel', description: 'Rol paneli' }, (ctx) => ctx.reply({
content: 'Rolünü seç 👇',
components: [
new ActionRow(new Button('rol_oyuncu', 'Oyuncu', 'primary', '🎮'), new Button('rol_cizer', 'Çizer', 'success', '🎨')),
new ActionRow(new SelectMenu('bildirim', [], 'Bildirimler').option('Duyurular', 'duyuru').option('Etkinlikler', 'etkinlik').range(0, 2)),
],
}));
bot.on('interaction', async (ix) => {
if (ix.customId === 'rol_oyuncu') return ix.update({ content: `🎮 ${ix.user.username} oyuncu oldu`, components: [] });
if (ix.customId === 'bildirim') return ix.reply(`Seçimin: ${ix.values.join(', ') || 'hiçbiri'}`);
return ix.defer();
});
bot.start();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
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öntemMethod | Açı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 / getMessages | Tepki ve mesaj işlemleriReactions and messages |
bot.getServer / getChannels / getMembers / firstTextChannel | Sunucu 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();# zar_bot.py — Python 3.8+ (pip install requests)
import os, random, time, requests
API = "https://tawny.com.tr/api/v1"
H = {"Authorization": "Bot " + os.environ["TAWNY_TOKEN"]}
PREFIX = "!"
def api(method, path, body=None):
r = requests.request(method, API + path, json=body, headers=H, timeout=40)
if r.status_code == 429:
time.sleep(r.json().get("retry_after", 5))
return api(method, path, body)
return None if r.status_code == 204 else r.json()
COMMANDS = {
"ping": lambda: "Pong! 🏓",
"zar": lambda: "🎲 " + str(random.randint(1, 6)),
"yardim": lambda: "Komutlar: !ping, !zar, !yardim",
}
print("Bağlandı:", api("GET", "/users/@me")["username"])
cursor = ""
while True:
try:
data = api("GET", "/gateway/events?wait=25&cursor=" + cursor)
cursor = data["cursor"]
for ev in data["events"]:
msg = ev["data"]
if ev["type"] != "MESSAGE_CREATE" or msg["author"]["bot"]:
continue
text = msg["content"].strip()
if not text.startswith(PREFIX):
continue
cmd = COMMANDS.get(text[len(PREFIX):].split()[0].lower() if len(text) > 1 else "")
if cmd:
api("POST", "/channels/" + str(msg["channel_id"]) + "/messages", {"content": cmd()})
except Exception as e:
print(e)
time.sleep(3)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.