Uygulama, bir programı Otag sunucusuna getirir. İnsanlar komutlarını çalıştırır, paylaştığı kartlardaki düğmelere basar, formlarını doldurur; uygulama da yanıt verir: kanala bir kart, yalnızca o kişinin gördüğü bir yanıt, bir form ya da herkesin gördüğü bir kartta bir değişiklik. Execute’un CS2 maçları da böyle bir uygulamadır ve tam olarak bu sayfada anlatılanlarla yapılmıştır.
Uygulamanı istediğin dilde yazabilirsin. Otag’la HTTPS üzerinden, istersen bir de WebSocket üzerinden konuşur: Otag ona insanların yaptıklarını gönderir, o da Otag’ın API’sini kendi adına çağırır.
- Bir yapay zekâ kodlama ajanıyla mı geliştiriyorsun? Ona Otag uygulama becerisini ver: aşağıdaki her şeyi ona öğreten tek bir dosya (İngilizce).
- Çalışan bir koddan mı başlamak istiyorsun? Örnek uygulamayı indir (TypeScript, çalıştırmak için hiçbir paket gerekmez) ya da README’sini oku (İngilizce).
Hızlı başlangıç
- Uygulamayı oluştur. Otag’da Ayarlar → Geliştirici → Yeni uygulama’yı aç. Otag uygulamanın jetonunu bir kez gösterir: kopyala ve gizli tut. Uygulamanın sayfasında uygulama kimliğini ve imza anahtarını da bulursun.
- Neler istediğini seç. "İstedikleri" altında, uygulamanın eklendiği yerde neye ihtiyacı varsa onu aç (örneğin Kanalları görüntüle ve Mesaj gönder) ve kaydet.
- Çalıştır. Örnek uygulamayı uygulamanın kimliği ve jetonuyla başlat ya da kendi kodunu çalıştır. Otag’ın gateway’ine bağlanabildiği için kendine ait bir adres gerekmeden kendi bilgisayarında çalışır.
- Sunucuna ekle. Sunucu ayarları → Entegrasyonlar’ı aç, uygulama kimliğini "Bağlantıyla ya da kimlikle ekle" altına yapıştır ve ekle. Bunun için orada Sunucuyu yönet iznin olmalı.
- Kullan. Sunucunun metin kanallarından birinde
/yaz: komutları listelenir.
Uygulamalar nasıl çalışır
Uygulama bir üyedir. Kendine ait bir hesabı vardır; bu hesap UYGULAMA etiketi taşır ve eklendiği her sunucuya katılır. Orada kendine ait bir rolü olur: uygulamanın adını taşır ve onu ekleyen kişinin en yüksek rolünün hemen altında yer alır (sunucunun sahibi ya da bir yönetici eklediğinde en üstte). Böylece onu ekleyenin yapamayacağı bir şeyi kimseye yapamaz. İstediği izinleri alır; ekleyen kişi bazılarını kapatırsa daha azını. Bu rolü başka kimse taşıyamaz; kimse onu uygulamadan alamaz ya da silemez. Uygulama atılmaz ya da yasaklanmaz: Entegrasyonlar’dan kaldırılır. Kendi sunucusunu, arkadaşını ya da sohbetini kurmaz.
İnsanlar onu üç yoldan kullanır. Komutlarını çalıştırır (/ yazarak ya da mesaj kutusunun + menüsünden seçerek), kartlarındaki düğmelere basar ve menülerden seçer, açtığı formları doldurur. Bunların her biri uygulamaya bir etkileşim olarak ulaşır; uygulama da üç saniye içinde yanıt verir.
İki gizli bilgi. Jeton (otb_…) uygulamanın kendisidir: elinde bulunduran uygulama adına iş yapar. Bu yüzden onu sunucunda tut; asla bir web sayfasına ya da insanların indirdiği bir uygulamaya koyma. İmza anahtarı bir şeyin Otag’dan geldiğini kanıtlar: Otag, uygulamaya gönderdiği her etkileşimi onunla imzalar.
Etkileşimleri duymanın iki yolu. Uygulamaya bir etkileşim adresi (https) ver; Otag her etkileşimi oraya imzalayarak gönderir. Ya da adresi boş bırak ve Otag’ın gateway’ine (bir WebSocket) uygulama olarak bağlan: Otag etkileşimleri bunun yerine oradan gönderir. Gateway’in kendine ait bir adrese ihtiyacı yoktur, bu yüzden kendi bilgisayarın için uygundur; adres ise bir sunucuda çalışan uygulamaya uyar. Adres ayarlıysa Otag yalnızca adresi kullanır.
Kimler kullanabilir. Her sunucuda, sunucuyu yönetenler uygulamanın komutlarını kimlerin çalıştırabileceğini seçer (herkes ya da bazı roller). Bir karttaki düğmeye basmak için kanalı görebilmek yeterlidir; bir düğme yalnızca bazı kişilere de gösterilebilir. Her etkileşim, uygulamaya o kişinin komutlarını kullanıp kullanamayacağını da söyler.
Merhaba der. Uygulamayı ekleyen kişi, onun kendini tanıtacağı bir kanal seçer; uygulamaya da orada ne paylaşacağı sorulur (bkz. Merhaba demek).
Uygulamayı oluşturmak ve ayarlamak
Buradaki her şey Ayarlar → Geliştirici’de, uygulamanın sayfasındadır.
| Ayar | Nedir |
|---|---|
| Ad | 2 ile 32 karakter. Uygulamanın hesabı bu adı taşır. |
| Simge | Uygulamanın resmi; hesabında ve uygulama listesindeki kartında görünür. En çok 2 MB ve kenarı en çok 1024 piksel. |
| Logo | Uygulamanın saydam zemin üzerindeki logosu; birleşik logoda Otag’ınkinin yanında durur ("Otag × Uygulama"). PNG, WebP ya da GIF; en çok 2 MB ve kenarı en çok 1024 piksel. |
| Açıklama | Ne yaptığı, en çok 400 karakter. Uygulama listesinde ve kartında görünür. |
| Renk | #RRGGBB. Uygulamanın kartlarının kenarını ve ilk düğmelerini boyar. |
| Etkileşim adresi | Otag’ın etkileşimleri gönderdiği bir http ya da https adresi. Kaydettiğinde Otag ona ping atar: uygulama 5 saniye içinde {"type": "pong"} yanıtını vermelidir, yoksa adres kaydedilmez. Gateway’i kullanmak için boş bırak. |
| İmza anahtarı | Otag’ın etkileşimleri imzaladığı anahtar. Yeni anahtar başkasını oluşturur; eskisi hemen çalışmaz olur. |
| Jeton | Uygulama oluşturulurken bir kez gösterilir. Yeni jeton başkasını oluşturur, eskisini durdurur ve uygulamanın gateway bağlantılarını kapatır. |
| İstedikleri | Uygulamanın eklendiği yerde istediği izinler (bkz. İzinler). |
| Herkes ekleyebilir | Açıkken bir sunucuyu yöneten herkes onu bağlantısıyla ya da kimliğiyle ekleyebilir. Kapalıyken yalnızca sen. |
| Uygulama listesi | Otag’ın yöneticilerinden onu listelemelerini iste (bkz. Uygulama listesine girmek). |
| Uygulama kimliği | Uygulamayı eklemek için kimliği. Eklemeye bağlantı vermek için: otag://app/<uygulama kimliği> Otag’ın masaüstü uygulamasını onunla açar; Otag’ın web uygulaması da adresinin sonuna ?app=<uygulama kimliği> eklenince açar. |
En çok 10 uygulama oluşturabilirsin. Bir uygulamayı silmek onu her sunucudan çıkarır; paylaştıkları "Deleted app" adıyla kalır.
Otag’ı uygulama olarak çağırmak
Otag’ın API’si https://api.otag.chat/api/v1 adresindedir. Uygulama jetonunu her istekle gönderir:
Authorization: Bot otb_…
Content-Type: application/json
Gövdeler ve yanıtlar JSON’dır. Her kimlik bir metindir (string). Uygulama, her sunucudaki rolünün izin verdiği ölçüde şunları çağırabilir:
| Ne | Uç noktalar |
|---|---|
| Sunucuları, kanalları, rolleri ve üyeleri | GET /state (uygulamanın gateway READY’sinin taşıdığı her şey), GET /guilds/{gid}/members, GET /guilds/{gid}/roles, GET /users/{id} |
| Mesajlar | GET /channels/{id}/messages?before={message_id}&limit=50, POST /channels/{id}/messages {content?, card?, thread_id?, also_in_channel?, reply_to?, reply_mention?, poll?, title?, tag_ids?}, PATCH /channels/{id}/messages/{mid} {content?, card?}, DELETE /channels/{id}/messages/{mid}, GET /channels/{id}/messages/{mid}/thread?before={message_id}&limit=50 (mesaj ve yanıtları, {root, replies}) |
| Anketler | PUT /channels/{id}/messages/{mid}/poll/votes {option_ids}, POST /channels/{id}/messages/{mid}/poll/close |
| Forumlar | GET /channels/{id}/posts?sort=&tags=&q=&after=&limit=30 ({posts, next?}), PATCH /channels/{id}/posts/{mid} {title?, tag_ids?, pinned?, locked?} |
| Tepkiler | PUT ve DELETE /channels/{id}/messages/{mid}/reactions/{emoji} |
| Sabitlenmiş mesajlar | GET /channels/{id}/pins?thread_id= (en son sabitlenen başta), PUT ve DELETE /channels/{id}/pins/{mid} (Mesajları yönet) |
| Arama | GET /search?q=&channel_id=&author_id=&limit= |
| Kanallar ve kategoriler | POST /guilds/{gid}/channels {kind: "text", "forum" ya da "voice", announcement?, name, topic?, category_id?, position?}, PATCH ve DELETE /channels/{id}, POST /guilds/{gid}/categories, PATCH ve DELETE /categories/{id}, PUT ve DELETE /channels/{id}/overrides/{role_id} |
| Üyeler | PATCH /guilds/{gid}/members/{id} {role_ids?, nick?}, DELETE /guilds/{gid}/members/{id} (atma), GET /guilds/{gid}/bans, PUT ve DELETE /guilds/{gid}/bans/{id} |
| Ses | GET /guilds/{gid}/voice (kim hangi ses odasında: [{user_id, channel_id, self_mute, self_deaf, server_mute, streaming, camera}]), POST /voice/{user_id}/move {channel_id}, PUT ve DELETE /voice/{user_id}/mute, DELETE /voice/{user_id} (bağlantıyı kesme) |
| Kendisi | GET /apps/{id}, GET ve PUT /apps/{id}/commands, GET /guilds/{gid}/apps, POST /guilds/{gid}/leave (uygulamayı o sunucudan çıkarır) |
Bunların dışındaki her şey 403 app_not_allowed yanıtını verir. Mesajlar en çok 4000 karakter markdown taşır; <@user_id> birini anar. thread_id, kanaldaki bir mesajın altındaki mesaj dizisinde yanıtlar; also_in_channel: true yanıtı kanalda da gösterir. Geçmiş, dizisinde kalan yanıtları içermez ve her yanıt kendi thread_id’sini taşır. reply_to, kanalda görünen bir mesajı alıntısıyla birlikte yanıtlar; reply_mention: true o mesajın yazarından bahseder. poll: {options, multi?} anket açar; content sorudur (en çok 300 karakter; en çok 100 karakterlik 2-12 seçenek). Oylar POLL_VOTE ile gelir, anket düzenlenemez. Forumda (forum türündeki kanal) mesaj, title ve isteğe bağlı olarak kanalın forum.tags listesinden tag_ids taşıyan bir gönderidir; yanıtları altındaki dizidir, bu yüzden thread_id her yerde olduğu gibi yanıtlar. Duyuru kanalı (announcement: true), @everyone'ın yazamadığı bir metin kanalıdır: uygulamanın rolüne bir izin tanımı ile yazma izni ver ya da webhook ile paylaş. İki çubuk arasındaki sözler (||böyle||) spoiler sayılır: uygulamalar biri tıklayana dek onları gizler. Konuşmasına sabitlenmiş bir mesaj pin {user_id, pinned_at} taşır; sabitlemek de konuşmaya kimsenin sözü olmayan bir satır yazar: system {kind: "pin", message_id} taşıyan, yazarı sabitleyen kişi olan bir mesaj. Bu satırlara dokunma: yanıt, tepki ya da düzenleme almazlar. İnsanların gönderdiği bir mesaj, yazısız bir sesli mesaj olabilir (voice: true işaretli tek bir eki vardır; süresi duration_ms, dalga biçimi waveform) ya da yazısız bir çıkartma (sticker_id taşır; çıkartma durdukça sticker da gelir); ikisi de düzenlenmez. Uygulama saniyede en çok 5 mesaj paylaşır (bir seferde 20’ye kadar). Uygulama ses odalarına katılmaz.
Komutlar
Uygulama komutlarını jetonuyla kendisi ayarlar:
PUT /apps/{app_id}/commands
[
{
"name": "match",
"description": "Open a match",
"description_localizations": {"tr": "Maç aç"},
"menu": true,
"options": [
{"name": "map", "description": "The map", "type": "string", "required": false,
"choices": [{"name": "Mirage", "value": "de_mirage"}, {"name": "Nuke", "value": "de_nuke"}]}
]
}
]
Liste uygulamanın komutlarının yerini alır; en çok 50 komut. Uygulama her başladığında gönder: ucuzdur ve sunucular değişikliği duyar.
| Alan | Kurallar |
|---|---|
name |
1 ile 32 arası küçük harf, rakam, - ve _; benzersiz. İnsanlar /ad yazar. |
description |
1 ile 100 karakter. description_localizations başka dillerde koduyla verir, örneğin {"tr": "…"}. |
menu |
true olduğunda komut, açıklamasıyla mesaj kutusunun + menüsünde de listelenir. |
options |
En çok 10 tane: {name, description, description_localizations?, type, required?, choices?}. type: string, integer, boolean, user (sunucudaki biri) ya da channel (kanallarından biri). choices ([{name, value}]) bir string ya da integer seçeneğini bunlarla sınırlar. |
Otag bir komutu uygulamaya ulaşmadan önce denetler: kişi uygulamayı orada kullanabilmeli, her seçenek de türüne ve seçeneklerine uymalıdır (yoksa 422 missing_option ve invalid_option). Uymayan bir liste 422 invalid_command olur.
Etkileşimleri almak
Bir adreste
Otag her etkileşimi uygulamanın etkileşim adresine JSON olarak, iki başlıkla gönderir:
| Başlık | Ne taşır |
|---|---|
X-Otag-Timestamp |
Otag’ın gönderdiği an, Unix saniyesi olarak. |
X-Otag-Signature |
sha256= ve <timestamp>.<gövde> metninin, uygulamanın imza anahtarıyla alınan HMAC-SHA256’sının onaltılık hâli. |
Her şeyden önce ikisini de, gövde geldiği hâliyle, denetle: imza tutmuyorsa ya da zaman damgası şu andan beş dakikadan fazla uzaksa isteği reddet (401). Sonra üç saniye içinde 200 ve JSON yanıtla dön.
import { createHmac, timingSafeEqual } from 'node:crypto';
function fromOtag(secret: string, timestamp: string, signature: string, body: Buffer): boolean {
if (!signature.startsWith('sha256=')) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const want = createHmac('sha256', secret).update(`${timestamp}.`).update(body).digest();
const got = Buffer.from(signature.slice(7), 'hex');
return got.length === want.length && timingSafeEqual(got, want);
}
Adresi kaydettiğinde Otag aynı biçimde bir ping gönderir; ardında bir kişi yoktur: {"type": "pong"} yanıtını ver.
Gateway üzerinden
Etkileşim adresi yoksa uygulama etkileşimleri Otag’ın gateway’inde duyar:
https://api.otag.chat/api/v1/gatewayadresine bir WebSocket aç (https://içinwss://).{"t": "IDENTIFY", "d": {"token": "otb_…"}}gönder.- Otag uygulamanın sunucuları ve
heartbeat_msileREADYyanıtını verir; ardından o sunucuların olaylarını bir üyeye gönderdiği gibi, uygulamaya gelen her etkileşimi deINTERACTION_CREATEile gönderir. - Her birine üç saniye içinde yanıt ver: gövdesi yanıtın kendisi olan
{type, data?, open?}ilePOST /interactions/{id}/{token}/callback.
Her çerçeve {"t": "<TÜR>", "d": {…}} biçimindedir. Otag soketi her heartbeat_ms’de (25 saniye) ping’ler; çoğu WebSocket istemcisi kendiliğinden yanıt verir. Kopan bir bağlantıyı fark etmek için aynı sıklıkta {"t": "PING"} gönder ve {"t": "PONG"} bekle; 15 saniye boyunca gelmezse yeniden bağlan. Yeni bir bağlantı baştan bir READY alır.
Bir etkileşimde neler var
{
"id": "105372067926376450",
"token": "…",
"type": "command",
"app_id": "105372067926376448",
"guild_id": "105372067704078336",
"channel_id": "105372067725049856",
"user": {"id": "105372067603415040", "username": "alice", "display_name": "Alice"},
"member": {"role_ids": ["…"], "nick": "Ali", "permissions": "3", "can_use_commands": true},
"locale": "en",
"data": {"name": "match", "options": {"map": "de_mirage"}}
}
| Alan | Nedir |
|---|---|
id, token |
Etkileşim ve onu 15 dakika boyunca takip etmeyi sağlayan jeton (bkz. Sonradan yanıtlamak). |
type |
command, action, form, configure, added ya da ping. |
user |
Bunu kim yaptı. member onun o sunucudaki hâlidir: rolleri, takma adı, oradaki izinleri (onluk sayı olarak bir metin) ve can_use_commands: sunucunun ona uygulamanın komutlarını kullanma izni verip vermediği. |
locale |
Kişinin Otag’ının şu an konuştuğu dil: en ya da tr. O dilde yanıt ver. |
data |
command için {name, options}, seçenekler adlarıyla. action için {action_id, values?, message_id?} (bir yanıttaki düğme için reply_id?), kartın message’ıyla birlikte. form için {form_id, values, message_id?}. configure ve added için {}. |
Yanıt vermek
Yanıt {type, data?, open?} biçimindedir:
type |
Ne olur |
|---|---|
reply |
data: {content?, card?} yalnızca o kişiye, kanalın en altında, "Bunu yalnızca sen görüyorsun" işaretiyle görünür. |
message |
data: {content?, card?} uygulama tarafından kanala, herkes için paylaşılır. Uygulamanın orada Kanalları görüntüle ve Mesaj gönder izinleri olmalıdır. |
update |
Bir düğme ya da menü için: data: {content?, card?} tıklanan mesajı (ya da yanıtı) değiştirir. Her parça yalnızca verildiğinde değişir; "card": null kartı kaldırır. |
form |
data kişiye açılan bir formdur (bkz. Formlar). Bir formun kendi gönderimine yanıt olarak verilmez. |
defer |
Şimdilik hiçbir şey: uygulama sonra yanıtlar (bkz. Sonradan yanıtlamak). |
open |
data: {url, window?} kişi için bir bağlantı açar. |
pong |
Yalnızca ping için. |
Her yanıt ayrıca open: {url, window?} taşıyabilir. Bağlantı http, https ya da steam://connect ve steam://run olabilir; window: "popup" bir https adresini Otag’ın üzerinde, ondan ayrı küçük bir pencerede açar: giriş yapmak için.
Uygulamaya ulaşılamadığında Otag bunu kişiye söyler ve uygulamanın yanıtı kullanılmaz: adres de gateway bağlantısı da yoksa (503 app_offline), üç saniye içinde yanıt gelmezse (504 app_timeout) ya da yanıt uymuyorsa (502 app_error ya da uymayanın 422’si).
Sonradan yanıtlamak
Bir etkileşimden sonraki 15 dakika boyunca uygulama, başka bir giriş gerekmeden yalnızca etkileşimin id ve token’ı ile onu takip edebilir (saniyede bir, bir seferde 20’ye kadar):
| İstek | Ne yapar |
|---|---|
PATCH /interactions/{id}/{token}/reply {content?, card?, close_window?} |
Kişinin gördüğü yanıtı ayarlar ya da değiştirir. close_window: true, girişin bittiğinde kişinin Otag’ının o yanıttan açtığı pencereyi kapatır. |
DELETE /interactions/{id}/{token}/reply |
Yanıtı geri alır. |
POST /interactions/{id}/{token}/messages {content?, card?} |
Kanala paylaşır. |
PATCH /interactions/{id}/{token}/message {content?, card?} |
Tıklanan mesajı değiştirir. |
Uzun süren işler için yol: hemen defer yanıtını ver, işi yap, sonra takip et.
Merhaba demek
Uygulamayı bir sunucuya ekleyen kişi, uygulamanın kendini tanıtacağı yazı kanallarından birini seçer ya da hiçbirini seçmez. Ardından uygulamaya bir added etkileşimi gelir: channel_id o kanaldır, user ve member onu ekleyen kişi, locale de onun dilidir. Ya bir message ile yanıt ver (Otag onu oraya uygulama olarak paylaşır) ya da defer ile yanıt verip 15 dakika içinde POST /interactions/{id}/{token}/messages ile paylaş. Başka bir yanıt paylaşılmaz.
Merhaba, sunucunun uygulamayla ilk tanışmasıdır ve kanaldaki herkes onu görür: uygulamanın ne yaptığını ve nasıl başlanacağını bir iki satırda söyle, ilk adımı da bir düğmeye koy. Uygulamaya yalnızca o kanala yazabiliyorsa sorulur; uygulamayı eklemek merhabayı hiç beklemez ve oradaki ayarları değiştiğinde ona yeniden sorulmaz.
Kartlar
Bir uygulamanın mesajı ya da yanıtı bir kart taşıyabilir:
{
"color": "#13877B",
"title": "Team A vs Team B",
"status": {"text": "Open · 1 of 10 seated", "tone": "accent"},
"description": "5v5 · Mirage",
"lists": [
{"title": "Team A", "people": [{"user_id": "105372067603415040", "note": "Host"}], "slots": 5},
{"title": "Team B", "people": [], "slots": 5}
],
"actions": [
{"type": "button", "id": "join:b", "label": "Join Team B", "style": "primary"},
{"type": "button", "id": "start", "label": "Start", "style": "success", "users": ["105372067603415040"]},
{"type": "link", "label": "Open in the app", "url": "https://example.com/match/1"}
],
"footer": "Room 3BUGRA"
}
| Alan | Kurallar |
|---|---|
color |
#RRGGBB, kartın kenarı. Verilmezse uygulamanın rengi. |
title |
En çok 120 karakter. url (http ya da https) onu bir bağlantı yapar. |
description |
Markdown, en çok 2000 karakter. |
image, thumbnail |
Üstte boydan boya bir afiş ve başlığın yanında küçük bir resim: http ya da https (bkz. Resimler). |
status |
{text, tone}: kısa bir satır (en çok 100); tone değeri neutral, accent (uygulamanın rengi), success, warning, danger ya da live (uygulamanın rengi, hareketli). |
fields |
En çok 12 tane {name, value, inline?}: ad en çok 64, değer en çok 512 karakter markdown. |
lists |
En çok 4 tane, örneğin takımlar: {title?, people, slots?, empty?}. En çok 12 kişi (people); her biri {user_id} (Otag’daki biri, Otag’ın gösterdiği gibi çizilir) ya da {name}, en çok 32 karakterlik bir note ile. slots (en çok 12) boş yerleri empty adıyla çizer. |
footer |
En çok 200 karakter. |
actions |
En çok 10 tane, aşağıda. |
| Eylem | Alanlar |
|---|---|
| Düğme | {type: "button", id, label, style?, disabled?}: style değeri primary, secondary (varsayılan), success ya da danger. |
| Bağlantı | {type: "link", label, url, window?}: yanıtlardaki bağlantılar gibi. Bağlantı uygulamaya ulaşmaz, yalnızca açılır. |
| Menü | {type: "select", id, placeholder?, options}: en çok 25 tane {value, label, description?}; seçim data.values olarak gelir. |
Her id kartta benzersizdir ve en çok 100 karakterdir; etiketler en çok 40 karakterdir. users bir eylemi yalnızca o kişilere gösterir, except onlardan gizler (her biri en çok 100 kişi). Bir kart bir şey göstermelidir ve kartları yalnızca uygulamalar ve webhook’lar paylaşır. Uymayan her şey neyin uymadığını söyleyen 422 invalid_card olur. Yalnızca bir mesajın kartını değiştirmek onu düzenlenmiş olarak işaretlemez.
Düğmeler tıklamalar arasında bir şey saklamayı gerektirmez: bir id, uygulamanın ona yanıt vermek için ihtiyaç duyduğunu taşıyabilir (wave:3, join:b).
Kanalı görebilen herkes bir karttaki düğmelere basabilir. Bir komutun yaptığını yapan bir düğmede member.can_use_commands alanına bak ve kullanamayanlara bir yanıtla karşılık ver.
Formlar
{
"id": "match",
"title": "Open a match",
"submit": "Open",
"sections": [
{"fields": [
{"type": "choice", "id": "mode", "label": "Mode", "style": "segmented", "value": "5v5",
"options": [{"value": "5v5", "label": "5v5"}, {"value": "1v1", "label": "1v1"}]},
{"type": "multi", "id": "maps", "label": "Maps", "min": 1, "max": 3,
"options": [{"value": "de_mirage", "label": "Mirage"}, {"value": "de_nuke", "label": "Nuke"}],
"show_when": {"field": "mode", "is": ["5v5"]}}
]},
{"title": "More options", "collapsed": true, "fields": [
{"type": "toggle", "id": "knife", "label": "Knife round", "value": true},
{"type": "text", "id": "name", "label": "Team name", "max_length": 32}
]}
]
}
En çok 5 bölüm ve 25 alan. Bir bölümün title’ı olabilir ve collapsed olarak kapalı başlayabilir. Bir alan {type, id, label, description?, placeholder?, required?, value?, show_when?} biçimindedir:
type |
Nedir |
|---|---|
text |
Metin: max_length (en çok 4000, varsayılan 200), multiline?. |
number |
min?, max?, step?. |
toggle |
Açık ya da kapalı. |
choice |
options’dan biri; tiles, list ya da segmented olarak. |
multi |
options’dan min ile max arasında birkaçı; tiles ya da list olarak. |
select |
options’dan biri, bir menüden. |
note |
Yalnızca yazı, doldurulacak bir şey yok. |
Seçenekler {value, label, description?, image?, group?} biçimindedir, en çok 50 tane: image bir kutucuğa resim koyar, group ardından gelen seçeneklere başlık olur. show_when bir alanı yalnızca daha önceki bir choice, select ya da toggle ("true", "false") is içindekilerden birini tuttuğu sürece gösterir.
Kişi formu bir kez gönderir. Uygulama values içinde görünen her alanı id’siyle taşıyan bir form etkileşimi alır: metin, sayı, true ya da false veya bir liste. Otag önce bunları denetler (422 missing_value ve invalid_value, alanın adıyla).
Bir sunucudaki ayarlar
Bir sunucuyu yöneten biri Sunucu ayarları → Entegrasyonlar → uygulaman → Ayarları’nı açtığında, uygulama o sunucu için bir configure etkileşimi alır. Bir formla yanıt ver; gönderimi bir form etkileşimi olarak geri gelir. Ayarları kendi tarafında sunucu sunucu sakla ve kaydedilirken member.permissions’ı denetle: Sunucuyu yönet 32768’dir.
Resimler
Otag kartların ve formların bağladığı resimleri (PNG, JPEG, GIF ya da WebP; en çok 4 MB ve kenarı en çok 4096 piksel) kendisi indirir ve her adres için bir kez saklar. İnsanların Otag’ı bunları uygulamanın adresinden değil, Otag’dan yükler. Otag’ın indiremediği resim gösterilmez; özel ya da yerel bir ağdaki adres asla indirilmez.
Webhook’lar
Yalnızca paylaşım yapan bir sistem için (bir derleme sunucusu, bir izleme aracı, bir mağaza) webhook bir uygulamadan daha basittir. Sunucu ayarları → Entegrasyonlar → Webhook’lar’da bir tane oluştur: kendi adı ve resmiyle tek bir kanala, bir kez gösterilen bir adresten paylaşır.
POST https://api.otag.chat/api/v1/webhooks/{id}/{token}
Content-Type: application/json
{"content": "Build 128 passed", "card": {"title": "main", "status": {"text": "Passed", "tone": "success"}}}
Giriş gerekmez: adresin kendisi gizli bilgidir. Bir webhook’un kartı yalnızca bağlantı eylemleri taşır. Saniyede en çok 2 mesaj paylaşır (bir seferde 10’a kadar); ?wait=true paylaşılan mesajla yanıt verir.
İzinler
Uygulama izinleri tek bir sayı olarak, şunların toplamı olarak ister:
| İzin | Değer |
|---|---|
| Kanalları görüntüle | 1 |
| Mesaj gönder | 2 |
| Dosya ekle | 4 |
| Tepki ekle | 8 |
| Mesajları yönet | 16 |
| Bağlan (sese katılma) | 32 |
| Konuş | 64 |
| Ekran paylaş | 128 |
| Üyeleri sustur | 256 |
| Üyeleri taşı | 512 |
| Kanalları yönet | 1024 |
| Rolleri yönet | 2048 |
| Davet oluştur | 4096 |
| Üyeleri at | 8192 |
| Üyeleri yasakla | 16384 |
| Sunucuyu yönet | 32768 |
| Yönetici | 65536 |
| Takma adı değiştir | 131072 |
| Takma adları yönet | 262144 |
| Emoji ve süs ekle | 524288 |
| Emojileri ve süsleri yönet | 1048576 |
| Üyelere zaman aşımı ver | 4194304 |
| Denetim kaydını gör | 8388608 |
Kart paylaşan ve yanıt veren bir uygulamanın Kanalları görüntüle ve Mesaj gönder izinlerine ihtiyacı vardır (3). Kullandığından fazlasını isteme: onu ekleyenler listeyi görür ve bazılarını kapatabilir.
Sınırlar ve hatalar
| Sınır | |
|---|---|
| Hesap başına uygulama | 10 |
| Sunucu başına uygulama | 25 |
| Uygulama başına komut, komut başına seçenek | 50, 10 |
| Bir etkileşime yanıt süresi | 3 saniye (ping için 5) |
| Sonradan yanıtlar | 15 dakika, saniyede bir, bir seferde 20’ye kadar |
| Bir uygulamanın mesajları | Saniyede 5, bir seferde 20’ye kadar |
| Bir kişinin başlattığı etkileşimler | Saniyede 2, bir seferde 10’a kadar |
| Webhook paylaşımları | Saniyede 2, bir seferde 10’a kadar |
Hata, {code, message} ile birlikte bir durum kodudur. 429 rate_limited ne zaman yeniden denenebileceğini retry_after_ms ile söyler. Uygulamaların en sık karşılaştıkları:
| Kod | Anlamı |
|---|---|
unauthorized (401) |
Jeton yanlış ya da yenisiyle değiştirilmiş. |
app_not_allowed (403) |
Uygulamalar bunu çağıramaz. |
missing_permission (403) |
Uygulamanın rolünde orada o izin yok. |
invalid_card, invalid_form, invalid_command (422) |
Mesaj neyin uymadığını söyler. |
unknown_interaction (404) |
Etkileşimin 15 dakikası doldu ya da jetonu yanlış. |
app_offline, app_timeout, app_error |
Uygulama yanıt vermediğinde ya da uymayan bir yanıt verdiğinde insanların gördüğü. |
Uygulamanı denemek
- Geliştirirken onu gizli tut ("Herkes ekleyebilir" kapalı) ve kendine ait bir sunucuya ekle.
- Bilgisayarında gateway üzerinden çalıştır: adres de tünel de gerekmez. Etkileşim adresini yalnızca Otag’ın ulaşabileceği bir yerde ya da bilgisayarına bir tünel üzerinden çalıştığında ayarla.
- Yanıtlarını
trolarak görmek için Otag’ı Türkçeye çevir (Ayarlar → Uygulama → Dil). - Uygulamanın merhabasını yeniden görmek için onu Entegrasyonlar’dan sunucundan kaldır ve yeniden ekle.
- Uygulama geç yanıt verirse insanlar "Uygulama zamanında yanıt vermedi" uyarısını görür: önce
deferile yanıt ver, sonra takip et.
Uygulama listesine girmek
Sunucu yöneticileri uygulamaları Sunucu ayarları → Entegrasyonlar’daki listeden ekler; hangi uygulamaların görüneceğini ve hangilerinin öne çıkacağını Otag’ın yöneticileri seçer. Başvurmak için:
- Uygulamayı açık yap ("Herkes ekleyebilir"), bir açıklama ve bir simge ekle. Bir logo onun "Otag × Uygulama" birleşik logosunu oluşturur.
- Uygulamanın sayfasında, Uygulama listesi altında Listeye alınmayı iste’yi seç.
- Otag’ın yöneticileri inceler. Kararlarını bir e-postayla öğrenirsin; reddedilirse nedeni de yazar.
Listede olup gizli yapılan bir uygulama listeden çıkar. Açık bir uygulamayı, listede olsun olmasın, herkes bağlantısıyla ya da kimliğiyle ekleyebilir.
Güvende tutmak
- Jetonu sunucunda tut. Sızarsa hemen yenisini oluştur: eskisi çalışmaz olur.
- Uygulamaya gönderilen her etkileşimin imzasını denetle ve tutmayanları reddet.
- Uygulamanın kullandığı izinleri iste, fazlasını değil.
- İnsanlara yalnızca onların görmesi gerekeni göster: tek kişiye
replyile yanıt ver, eylemlerdeusersveexceptkullan.