İçeriğe geç
OtagGeliştiriciler

Otag için uygulama geliştir

Otag için uygulama, bot ve entegrasyon geliştirmenin yolu: komutlar, düğmeli kartlar, formlar, yanıtlar, webhook’lar ve tam başvuru kaynağı.

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ıç

  1. 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.
  2. 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.
  3. Ç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.
  4. 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ı.
  5. 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:

  1. https://api.otag.chat/api/v1/gateway adresine bir WebSocket aç (https:// için wss://).
  2. {"t": "IDENTIFY", "d": {"token": "otb_…"}} gönder.
  3. Otag uygulamanın sunucuları ve heartbeat_ms ile READY yanıtını verir; ardından o sunucuların olaylarını bir üyeye gönderdiği gibi, uygulamaya gelen her etkileşimi de INTERACTION_CREATE ile gönderir.
  4. Her birine üç saniye içinde yanıt ver: gövdesi yanıtın kendisi olan {type, data?, open?} ile POST /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ı tr olarak 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 defer ile 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:

  1. Uygulamayı açık yap ("Herkes ekleyebilir"), bir açıklama ve bir simge ekle. Bir logo onun "Otag × Uygulama" birleşik logosunu oluşturur.
  2. Uygulamanın sayfasında, Uygulama listesi altında Listeye alınmayı iste’yi seç.
  3. 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 reply ile yanıt ver, eylemlerde users ve except kullan.