Bir sunucuya bot ekleme¶

Bir bot, bot kapsamlı (scope) bir OAuth2 yetkilendirmesiyle sunucuya katılır. Sunucuda Sunucuyu Yönet (veya Yönetici) iznine sahip bir kişi yetkilendirme bağlantısını açar, sunucuyu seçer, istenen izinleri inceler ve onaylar. Ardından TEBHOS botu üye olarak ekler ve izin istenmişse ona tam olarak bu izinleri taşıyan bir rol verir.

Yetkilendirme bağlantısını oluşturma¶

https://tebhos.com/oauth2/authorize?client_id={application_id}&scope=bot&permissions={permissions}

Parametre	Zorunlu	Açıklama
client_id	Evet	Uygulama kimliği
scope	Evet	`bot`. Boşlukla ayrılarak (URL kodlamasında `+` veya `%20`) başka OAuth2 kapsamları da eklenebilir
permissions	Hayır	Botun rolü için izin bit kümesi, ondalık tamsayı dizesi olarak. Botu rolsüz eklemek için atlanır veya `0` kullanılır
guild_id	Hayır	Yetkilendirme ekranında bir sunucuyu önceden seçer
redirect_uri	Yalnız gerektiğinde	Kapsam yalnız `bot` değilse veya uygulamada `bot_require_code_grant` etkinse gerekir. Uygulamanın kayıtlı yönlendirme URI'lerinden biriyle eşleşmelidir
response_type	`redirect_uri` ile birlikte	`code`
state	Hayır	`redirect_uri` adresine geri döndürülen opak değer

TEBHOS uygulamasındaki uygulama sayfasında (Kullanıcı Ayarları, Geliştirici, Uygulamalar) bulunan OAuth2 URL oluşturucu bu bağlantıyı hazırlar: bot işaretlenir, izinler seçilir ve URL kopyalanır.

İzinleri seçme¶

permissions, botun ihtiyaç duyduğu izin bitlerinin toplamıdır. Tipik bir sohbet botunun ihtiyaçları:

İzin	Bit	Değer
Kanalı Görüntüle	`1 << 10`	1024
Mesaj Gönder	`1 << 11`	2048
Bağlantı Göm	`1 << 14`	16384
Dosya Ekle	`1 << 15`	32768
Mesaj Geçmişini Oku	`1 << 16`	65536
Tepki Ekle	`1 << 6`	64

Kanalı Görüntüle + Mesaj Gönder + Mesaj Geçmişini Oku = 68608:

https://tebhos.com/oauth2/authorize?client_id=1290847135893127168&scope=bot&permissions=68608

Bitlerin tam listesi İzinler sayfasındadır. Yalnız botun ihtiyaç duyduğu izinler istenmelidir; bilinmeyen veya ayrılmış bitler düşürülür.

Botu ekleyen kişinin ihtiyaçları¶

Hedef sunucuda Sunucuyu Yönet veya Yönetici iznine sahip, oturum açmış bir TEBHOS hesabı. İkisi de yoksa istek 403 ile başarısız olur.
Yönetici değilse yalnız kendisinde bulunan izinleri verebilir. Sahip olmadığı bir izni istemek 403 ile başarısız olur.
Uygulamada bot_public değeri false ise botu yalnız uygulamanın sahibi ekleyebilir. Diğer herkes 403 alır.

Sunucuda zaten üye olan bir bot yeniden eklenemez (409).

Bot eklendiğinde ne olur¶

Bot kullanıcısı sunucunun üyesi olur. Bot davetlerinde üye sayısı sınırları ve yasaklamalar denetlenmez.
permissions sıfır değilse TEBHOS, uygulamanın adını taşıyan ve tam olarak bu izinleri içeren (hiçbir şey miras alınmaz) bir rol oluşturur, rolü rol listesinin en üstüne yerleştirir ve bota atar.
Sunucu üyeleri bot için GUILD_MEMBER_ADD alır.
Bot gateway'e bağlıysa oturumu sunucuya bağlanır; bot önce GUILD_CREATE, ardından sunucunun olaylarını alır. Yeniden bağlanmak gerekmez.

Bundan sonra botun erişimi sıradan rol tabanlı erişimdir: sunucu yöneticileri rolünü düzenleyebilir veya silebilir, kanal izin geçersiz kılmaları da diğer üyelerde olduğu gibi bota uygulanır. Bkz. İzinler.

Grup DM'ye bot ekleme¶

Aynı akış botu bir sunucu yerine bir grup DM'ye de ekleyebilir. guild_id yerine channel_id={group_dm_id} gönderilir (ikisi asla birlikte gönderilmez). Yetkilendiren kişi o grup DM'nin üyesi olmalı, grupta da bir üye için daha yer bulunmalıdır. Zaten alıcı olan bir botu eklemek değişiklik yapmadan başarılı olur.

Yetkilendirme ekranı onayı aşağıdaki istekle verir; bu istek bir kullanıcı oturumuyla doğrudan da yapılabilir:

POST /oauth2/authorize/consent

Authorization: Bearer {session_token} gerektirir. Hız sınırı: IP adresi başına dakikada 60.

Alan	Tür	Açıklama
client_id	string	Uygulama kimliği
scope	string	`bot`, isteğe bağlı olarak başka kapsamlarla birlikte
guild_id?	string	Botun ekleneceği sunucu
channel_id?	string	Botun ekleneceği grup DM. `guild_id` ile birlikte kullanılamaz
permissions?	string	Ondalık dize olarak izin bit kümesi. Negatif veya tamsayı olmayan bir değer 400 döndürür
redirect_uri?	string	Kapsam yalnız `bot` değilse veya uygulama kod yetkisi (code grant) gerektiriyorsa zorunludur
response_type?	string	`code`. Yalnız başka kapsamlar varsa gerekir
state?	string	Yönlendirmeyle birlikte geri döndürülür

{ "redirect_to": "https://tebhos.com/?code=..." }

Botu ekleme başarısız olursa isteğin tamamı başarısız olur ve redirect_to içindeki yetkilendirme kodu hiçbir zaman geçerli olarak verilmez. OAuth2 akışının geri kalanı için bkz. OAuth2.

Botu kaldırma¶

Üyeleri At iznine sahip bir üye, botu diğer üyeler gibi üye listesinden kaldırabilir. Bot da DELETE /users/@me/guilds/{guild_id} ile kendiliğinden ayrılabilir. Uygulamayı silmek botunu tüm sunuculardan kaldırır, bkz. Bot oluşturma.