TEBHOS API¶

TEBHOS; metin kanalları, doğrudan mesajlar, ses ve ekran paylaşımı sunan, topluluklar için bir sohbet platformudur. Bu başvuru belgesi, istemcilerin, botların ve entegrasyonların kullandığı genel protokol yüzeylerini açıklar.

Bir istemci veya bot geliştirmek için HTTP API ve Gateway ile başlanır.
Bot yazmak için Bot rehberi izlenir.
Ses ve ekran paylaşımı için Ses sayfası okunur.

Hızlı bağlantılar¶

Bölüm	Kapsadığı konu
Kimlik doğrulama	Kimlik bilgisi türleri ve `Authorization` başlığı
HTTP API'ye genel bakış	Temel URL, istek ve yanıt kuralları
Gateway'e genel bakış	Gerçek zamanlı WebSocket bağlantısı
Bot rehberi	Bot oluşturma, bağlama ve bir topluluğa ekleme
Hatalar	Hata gövdesinin biçimi ve hata kodları
Hız sınırları	Kovalar, başlıklar ve 429 yanıtı
İzinler	İzin bitleri, roller ve izin geçersiz kılmaları
Snowflake'ler	64 bitlik kimlik biçimi
Medya vekili	Avatarlar, simgeler, ekler ve diğer medya
İndirmeler	Masaüstü uygulaması indirmeleri

Protokol yüzeyleri¶

Kaynakları okumak ve değiştirmek için HTTP API, güncellemeleri gerçek zamanlı almak için Gateway olayları kullanılır. Medya yolları yüklenen dosyaları, avatarları, simgeleri ve vekil üzerinden sunulan harici medyayı sağlar.

Yüzey	Adres
HTTP API	`https://tebhos.com/api/v1`
Gateway	`wss://tebhos.com/ws?v=1&encoding=json`
Web uygulaması	`https://tebhos.com`

Bu başvuru belgesindeki her HTTP yolu API temel URL'sine görelidir. Örneğin GET /channels/{channel_id}, GET https://tebhos.com/api/v1/channels/{channel_id} anlamına gelir.

Ortak sözleşmeler¶

Her işlemde ortak olan davranış için Kimlik doğrulama, Hatalar, Hız sınırları ve Diller sayfalarına bakılabilir. Kaynak kimliklerinin çoğu snowflake'tir. CAPTCHA işleme ve Ek yüklemeleri, birden çok işleme yayılan iki akışı açıklar. Her kaynak sayfası, bu ortak davranıştan nerede ayrıldığını belirtir.

Alan gösterimi¶

Alan tablolarında alan adından sonra gelen ? isteğe bağlı, türden önce gelen ? ise null olabilir anlamına gelir.

Alan	Tür	Anlamı
`name`	`string`	Zorunlu ve `null` olamaz
`name?`	`string`	İsteğe bağlı, ancak bulunduğunda `null` olamaz
`name`	`?string`	Zorunlu, ancak `null` olabilir
`name?`	`?string`	Atlanabilir veya `null` olarak ayarlanabilir

Atlanmış bir alan, null olarak ayarlanmış bir alandan farklıdır. Her işlem bu değerlerin kaynağı nasıl etkilediğini açıklar.

Tür sütununda array[type] adı verilen türden bir dizidir; map[key, value] ise anahtarları birinci türden, değerleri ikinci türden olan bir JSON nesnesidir. snowflake, ondalık bir dize olarak gönderilen 64 bitlik bir kimliktir.

Uç nokta keşfi¶

İşe örnek (instance) keşif belgesiyle başlanır. Bu belge kimlik doğrulama gerektirmez.

curl https://tebhos.com/api/v1/.well-known/tebhos

Yanıt örneği tanımlar: uç noktalarını, etkin özelliklerini, CAPTCHA sağlayıcısını, sınırlarını ve sürümünü. Nesnenin tamamı için Örnek sayfasına bakılabilir. Kısaltılmış bir örnek:

{
  "api_code_version": 1,
  "version": "0.1.0",
  "endpoints": {
    "api": "https://tebhos.com/api",
    "api_client": "https://tebhos.com/api",
    "api_public": "https://tebhos.com/api",
    "gateway": "wss://tebhos.com/ws",
    "media": "https://tebhos.com/api/v1",
    "webapp": "https://tebhos.com",
    "invite": "https://tebhos.com",
    "gift": "https://tebhos.com"
  },
  "features": {
    "voice_enabled": true,
    "presigned_attachment_uploads": true,
    "emails_enabled": true,
    "sms_enabled": false,
    "self_hosted": true,
    "payment_provider": "polar"
  },
  "captcha": {
    "provider": "hcaptcha",
    "hcaptcha_site_key": "00000000-0000-0000-0000-000000000000",
    "turnstile_site_key": null
  }
}

Temel URL'ler sabit kodlanmak yerine endpoints içinden okunmalıdır:

endpoints.api_public; botlar, kütüphaneler ve üçüncü taraf istemciler için API temelidir. endpoints.api ve endpoints.api_client şu an aynı değeri taşır.
API temeli sürümü içermez. Sonuna /v1 eklenir; böylece https://tebhos.com/api, https://tebhos.com/api/v1 olur.
endpoints.gateway Gateway URL'sidir. Gateway'e genel bakış sayfasında anlatıldığı gibi ?v=1&encoding=json ile bağlanılır.
endpoints.media, avatarlar ve simgeler gibi medya yollarının temelidir.

Keşif yolunun, istemci başına 60 saniyede 60 isteklik kendi hız sınırı vardır. Belge her istekten önce yeniden alınmak yerine önbelleğe alınmalıdır.

Kimlik bilgileri, Kimlik doğrulama sayfasında anlatıldığı gibi Authorization başlığında gönderilir.