Discord Bot İzinleri ve Rol Hiyerarşisi: Missing Permissions Hatasını Çözmek

Discord izinleri nedir ve bitfield nasıl çalışır?

Discord'da her izin, büyük bir tam sayının tek bir bitidir. Örneğin SEND_MESSAGES değeri 0x800 (1 << 11), ADD_REACTIONS değeri 0x40 (1 << 6) olarak tanımlıdır. Bir rolün ya da üyenin izinleri, bu değerlerin bit düzeyinde VEYA (|) ile birleştirilmesiyle elde edilir; bir iznin var olup olmadığı ise VE (&) işlemiyle kontrol edilir.

API v8 ve sonrasında tüm izin değerleri, overwrite içindeki allow ve deny alanları dahil, metin (string) olarak gönderilir. Değerler 32 biti çoktan aştığı için belgeler, izinleri dilinizin büyük tam sayı (BigInt) kütüphanesiyle işlemenizi önerir. discord.js bu yüzden izinleri bigint olarak tutar.

# Resmî belgedeki örnek: Send Messages (0x800) ve Add Reactions (0x40)
permissions = 0x40 | 0x800  # 2112

(permissions & 0x40) == 0x40    # True
(permissions & 0x800) == 0x800  # True
(permissions & 0x2) == 0x2      # False (Kick Members yok)

En sık kullanılan izinler

Resmî listede 50'yi aşkın izin bulunur. Bot geliştirirken en çok karşınıza çıkanlar aşağıda. İlk sütun API adı, ikinci sütun discord.js'teki PermissionFlagsBits karşılığıdır. Discord istemcisi bazı izinleri farklı adla gösterir: belgeye göre arayüzdeki "Manage Permissions" aslında MANAGE_ROLES, "Timeout Members" ise MODERATE_MEMBERS iznidir.

Yıldızlı izinler belgede özel olarak işaretlidir: sunucuda sunucu genelinde iki adımlı doğrulama (2FA) zorunluysa, bu izinleri kullanan botun sahibi olan hesabın da 2FA kullanması gerekir. Tam liste ve kanal türleri için Discord Docs: Permissions sayfasına bakın.

Rol hiyerarşisi: bot neyi yapamaz?

Bir kullanıcının ya da botun "en yüksek rolü", sunucudaki position değeri en büyük olan rolüdür; @everyone rolü 0 konumundan başlar. Belgeler, izinlerin yanında bota şu hiyerarşi kısıtlarını uygular:

• Bot, yalnızca kendi en yüksek rolünden daha aşağıdaki rolleri başkalarına verebilir.
• Bot, kendi en yüksek rolünün altındaki rolleri düzenleyebilir; ama bu rollere yalnızca kendisinde olan izinleri ekleyebilir.
• Bot, rolleri yalnızca kendi en yüksek rolünün altında sıralayabilir.
• Bot, yalnızca en yüksek rolü kendi en yüksek rolünden aşağıda olan kullanıcıları atabilir, yasaklayabilir ve takma adlarını düzenleyebilir.

Sunucu sahibi bu hesaplamanın dışındadır: belgedeki örnek kodda sahip için doğrudan tüm izinler döner. Bu yüzden bot, sunucu sahibini hiçbir izinle atamaz ya da yasaklayamaz. Zaman aşımı konusunda da belge, sahiplerin ve ADMINISTRATOR iznine sahip kullanıcıların zaman aşımının izin kısıtlamasından muaf olduğunu belirtir.

Hiyerarşi dışındaki her şeyde izinler rol sırasına bakmaz. Belgedeki örnek: bir kullanıcının A ve B rolleri var; A rolü bir kanalda VIEW_CHANNEL iznini reddediyor, B rolü aynı kanalda izin veriyor. Rollerin sırası ne olursa olsun kullanıcı kanalı görebilir, çünkü rol overwrite'larında izin vermek reddetmenin önüne geçer.

Kanal izinleri hangi sırayla hesaplanır?

Kanal bazındaki izin geçersiz kılmaları (permission overwrite) bir rol veya üye için o kanalda izin açabilir ya da kapatabilir. Çakışma olduğunda Discord şu sırayı uygular; sonraki adım öncekini ezer:

• @everyone rolüne verilen temel izinler (sunucu düzeyi)
• Kullanıcının rollerinden gelen izinler (sunucu düzeyi)
• @everyone için kanal overwrite'ındaki deny değerleri
• @everyone için kanal overwrite'ındaki allow değerleri
• Kullanıcının rolleri için kanal overwrite'larındaki deny değerleri (hepsi birleştirilir)
• Kullanıcının rolleri için kanal overwrite'larındaki allow değerleri (hepsi birleştirilir)
• Üyeye özel overwrite'taki deny
• Üyeye özel overwrite'taki allow

Temel izinlerde ADMINISTRATOR varsa hesaplama burada durur ve tüm izinler verilir; kanal overwrite'ları uygulanmaz. Belgenin sözde kodunun kısaltılmış hali:

def compute_overwrites(base, member, channel):
    if base & ADMINISTRATOR == ADMINISTRATOR:
        return ALL
    perms = base
    everyone = overwrites.get(channel.guild_id)
    if everyone:
        perms &= ~everyone.deny
        perms |= everyone.allow
    allow = deny = 0
    for role_id in member.roles:
        ow = overwrites.get(role_id)
        if ow:
            allow |= ow.allow
            deny |= ow.deny
    perms &= ~deny
    perms |= allow
    ow_member = overwrites.get(member.user_id)
    if ow_member:
        perms &= ~ow_member.deny
        perms |= ow_member.allow
    return perms

Örtük (implicit) izinler

Bazı izinler mantıksal olarak başka izinlere bağlıdır. Bir kanalda VIEW_CHANNEL reddedilirse, SEND_MESSAGES açık görünse bile kullanılamaz. SEND_MESSAGES reddedilirse MENTION_EVERYONE, SEND_TTS_MESSAGES, ATTACH_FILES ve EMBED_LINKS da fiilen işe yaramaz. Ses ve sahne kanallarında CONNECT reddi de diğer izinleri örtük olarak kapatır.

Thread ve kategori senkronizasyonu

Thread'ler izinlerini üst kanaldan devralır; tek istisna SEND_MESSAGES iznidir. Thread içinde mesaj göndermek için SEND_MESSAGES_IN_THREADS gerekir. Bu konuyu thread ve forum kanalı rehberimizde ayrıca anlattık. Kategoriler için gerçek bir kalıtım yoktur: alt kanalın izinleri kategoriyle birebir aynıysa kanal "senkronize" sayılır ve kategorideki değişiklikler ona yansır. Alt kanalda değişiklik yaptığınız anda senkronizasyon bozulur.

"Missing Permissions" ve "Missing Access" hataları neden çıkar?

Discord API iki farklı JSON hata kodu döndürür ve ikisi sık karıştırılır:

50013 aldığınızda şu kontrol listesini sırayla uygulayın:

• Bot rolünde gereken izin açık mı? (örneğin rol vermek için Manage Roles)
• O kanalda bot rolünü veya @everyone'ı etkileyen bir deny overwrite'ı var mı?
• İşlem bir üye veya rol üzerindeyse, hedefin en yüksek rolü botun en yüksek rolünden aşağıda mı?
• Hedef sunucu sahibi mi? Sahip üzerinde atma, yasaklama ve takma ad işlemleri yapılamaz.
• Yıldızlı bir izin kullanılıyorsa ve sunucuda 2FA zorunluysa, uygulama sahibinin hesabında 2FA açık mı?

Diğer API hata kodlarının tamamı için Discord API hata kodları yazımıza bakabilirsiniz.

discord.js ile izin kontrolü

discord.js, izinleri PermissionsBitField sınıfıyla temsil eder; bayrak adları PermissionFlagsBits içinde PascalCase olarak bulunur (KickMembers, ManageRoles gibi). GuildMember#permissions yalnızca sunucu düzeyindeki temel izinleri verir. Belirli bir kanaldaki nihai izinler için GuildChannel#permissionsFor() veya GuildMember#permissionsIn() kullanılır.

const { PermissionFlagsBits, MessageFlags } = require('discord.js');

// Bir slash komutunun içinde:
const me = interaction.guild.members.me;
const kanal = interaction.channel;

// Botun bu kanaldaki nihai izinleri (overwrite'lar dahil)
const izinler = kanal.permissionsFor(me);
const eksik = izinler.missing([
  PermissionFlagsBits.ViewChannel,
  PermissionFlagsBits.SendMessages,
  PermissionFlagsBits.EmbedLinks,
]);

if (eksik.length > 0) {
  return interaction.reply({
    content: `Bu kanalda eksik izinlerim var: ${eksik.join(', ')}`,
    flags: MessageFlags.Ephemeral,
  });
}

Interaction üzerinden gelen interaction.appPermissions ve interaction.memberPermissions özellikleri de işe yarar. Bunlar API'deki app_permissions alanına dayanır: uygulamanın, etkileşimin geldiği yerdeki izin kümesidir.

Hiyerarşiyi koddan kontrol etmek

discord.js, hiyerarşi kurallarını sizin yerinize hesaplayan hazır özellikler sunar: GuildMember#kickable, bannable, manageable ve moderatable; roller için Role#editable. Rolleri karşılaştırmak için member.roles.highest ve Role#comparePositionTo() kullanılabilir.

const hedef = interaction.options.getMember('uye');

if (!hedef) {
  return interaction.reply({ content: 'Üye bulunamadı.', flags: MessageFlags.Ephemeral });
}
if (!hedef.kickable) {
  return interaction.reply({
    content: 'Bu üyeyi atamam: rolü benimkinden yüksek ya da eşit, veya sunucu sahibi.',
    flags: MessageFlags.Ephemeral,
  });
}
await hedef.kick('Moderasyon komutu');

Komutu kimin kullanabileceğini sınırlamak

Bir slash komutunun varsayılan olarak hangi izne sahip kullanıcılara görüneceğini default_member_permissions alanıyla belirlersiniz. discord.js'te bu SlashCommandBuilder#setDefaultMemberPermissions() metodudur. Değeri "0" yapmak, belirli bir overwrite tanımlanmadıkça komutu yöneticiler dışında herkese kapatır. Sunucu yöneticileri bu ayarı daha sonra değiştirebildiği için kodda da kontrol yapmaya devam edin.

const { SlashCommandBuilder, PermissionFlagsBits } = require('discord.js');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('at')
    .setDescription('Bir üyeyi sunucudan atar')
    .addUserOption((o) => o.setName('uye').setDescription('Hedef üye').setRequired(true))
    .setDefaultMemberPermissions(PermissionFlagsBits.KickMembers),
};

discord.py tarafında aynı iş için discord.app_commands.default_permissions dekoratörü, botun izinlerini kontrol etmek için discord.app_commands.checks.bot_has_permissions kullanılır. Slash komutlarının temelleri için slash komut oluşturma rehberine, Python ile başlangıç için discord.py bot yapımı yazısına bakın.

Sık Sorulan Sorular

Bota Administrator verdim, yine de bir üyeyi atamıyor. Neden?

Administrator izinleri açar ama rol hiyerarşisini aşmaz. Hedef üyenin en yüksek rolü botun en yüksek rolüyle aynı seviyede veya üstündeyse ya da hedef sunucu sahibiyse işlem yapılamaz. Bot rolünü listede yukarı taşıyın.

Bir rol kanalda izni reddediyor, diğeri veriyor. Hangisi kazanır?

Rol overwrite'larında tüm deny değerleri önce, tüm allow değerleri sonra uygulanır. Yani rollerden biri izin veriyorsa izin açık olur. Bunu yalnızca üyeye özel bir overwrite değiştirebilir.

Davet linkinde hangi izinleri istemeliyim?

Yalnızca botunuzun gerçekten kullandığı izinleri. Bir müzik botu için genellikle Connect ve Speak, moderasyon botu için ilgili moderasyon izinleri yeterlidir. Ayrıntılar sunucuya ekleme rehberinde.

İzin değerini sayı olarak saklamak güvenli mi?

Belge, değerlerin 32 bitten büyük olduğunu ve string olarak serileştirildiğini belirtir. JavaScript'te normal Number yerine BigInt kullanın, veritabanında da metin olarak saklayın.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Bot davet linki ve izinler · Discord API hata kodları · AutoMod ve moderasyon botu · Slash komut oluşturma · Thread ve forum kanalları · Discord bot nasıl yapılır