Discord Intent Nedir? Message Content, Privileged Intent ve Disallowed Intents Hatası

Gateway intent nedir?

Botunuz Discord'a bir WebSocket bağlantısıyla, yani gateway üzerinden bağlanır. Bağlantı kurulurken gönderilen Identify paketinde intents adlı bir sayı bulunur. Bu sayı bir bit alanıdır (bitfield): her bit bir grup olayı temsil eder. Örneğin GUILDS (1 << 0) biti açıksa sunucu oluşturma, kanal güncelleme, rol değişikliği gibi olaylar size gelir. Resmî belgeye göre bir intent'i Identify sırasında belirtmezseniz o intent'e bağlı olayların hiçbirini almazsınız.

Discord bu sistemi, uygulamaların gereğinden fazla veri işlemesini önlemek için getirdi. API v8 ve sonrasında intent belirtmek zorunludur. discord.js tarafında da durum aynıdır: discord.js rehberine göre intent belirtmeden bir Client oluşturursanız kütüphane hata fırlatır. Ayrıca gereksiz olay almamak performansı artırır, bant genişliğini ve bellek kullanımını düşürür.

Intent listesi ve bit değerleri

Aşağıdaki tablo resmî Gateway belgesindeki intent'leri, bit değerlerini ve tetikledikleri başlıca olayları özetler. Yıldızlı olanlar privileged intent'tir.

Kütüphaneler bu sayıları sizin yerinize hesaplar. discord.js'te GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages gibi sabitler; discord.py'de discord.Intents sınıfının guilds, messages, members, message_content gibi özellikleri kullanılır. Bit mantığını izinlerde de göreceksiniz; ayrıntı için Discord bot izinleri ve rol hiyerarşisi yazısına bakabilirsiniz.

Privileged intent nedir?

Bazı intent'ler taşıdıkları verinin hassasiyeti nedeniyle ek koşula bağlıdır. Discord bunlara privileged intent der ve şu an üç tanedir:

• GUILD_MEMBERS (Server Members Intent): üye katılma, ayrılma ve güncelleme olayları ile bir sunucunun tam üye listesini isteme yetkisi.
• GUILD_PRESENCES (Presence Intent): kullanıcıların çevrimiçi/çevrimdışı durumu, oynadığı oyun gibi aktiviteleri ve hangi platformda aktif olduğu.
• MESSAGE_CONTENT (Message Content Intent): mesaj nesnelerindeki content, embeds, attachments, components ve poll alanları.

Privileged intent'i kodda istemeden önce Developer Portal'da açmanız gerekir. Resmî belge ayrıca şunu vurgular: bir privileged intent'i yalnızca uygulamanızın çalışması için gerçekten gerekiyorsa ve Developer Policy ile uyumluysa açabilirsiniz. GUILD_MEMBERS ve GUILD_PRESENCES olayları API sürümünden bağımsız olarak varsayılan olarak kapalıdır.

Privileged intent'ler yalnızca gateway olaylarını değil HTTP API'yi de etkiler. Örneğin List Guild Members uç noktasını kullanmak için uygulamanızda GUILD_MEMBERS intent'inin etkin olması gerekir. Bu HTTP kısıtı, Identify sırasında hangi intent'leri gönderdiğinizden bağımsızdır.

10.000 kullanıcı eşiği ve inceleme süreci

Discord, 10 Haziran 2026'da privileged intent erişim kurallarını değiştirdi. Eskiden 100 sunucu eşiği vardı; artık eşik sunucu sayısına değil, uygulamanızı tüm sunucularda görebilen benzersiz kullanıcı sayısına göre belirleniyor. Güncel durum şöyle:

• 10.000 kullanıcının altındaki uygulamalar privileged intent'leri Developer Portal'dan açıp kapatabilir, başvuru gerekmez.
• Eşiğe ulaşan ve privileged intent kullanan uygulamaya Developer Portal'da bildirim gelir; başvuru için bildirim tarihinden itibaren 90 gün süre vardır. Bu sürede başvurulmazsa mevcut erişim kaldırılır.
• İnceleme sürerken uygulama istediği intent'lerle çalışmaya ve yeni sunuculara katılmaya devam edebilir.
• Erişim verilen uygulamalar her yıl yeniden başvurmak zorundadır.
• Uygulama doğrulaması (App Verification) ile privileged intent incelemesi artık ayrı süreçlerdir.

Başvuru sürecinin ayrıntılarını ve gerekçe yazma ipuçlarını Discord bot doğrulama ve privileged intent başvurusu yazısında ayrıca ele aldık.

Message Content intent olmadan ne olur?

MESSAGE_CONTENT diğer intent'lerden farklıdır: bir olayı açıp kapatmaz, olayların içindeki verileri etkiler. Bu intent olmadan da MESSAGE_CREATE olayını alırsınız (GUILD_MESSAGES açıksa), ancak kullanıcı girdisi içeren alanlar boş metin ya da boş dizi olarak gelir. Etkilenen alanlar content, embeds, attachments, components ve poll alanlarıdır.

Resmî belgeler, intent olmadan da içeriği alabildiğiniz istisnaları şöyle sıralar:

• Uygulamanızın kendi gönderdiği mesajlar.
• Uygulamanızla yapılan DM (özel mesaj) içerikleri.
• Uygulamanızın @mention ile etiketlendiği mesajlar.
• Bir message context menu komutunun üzerinde kullanıldığı mesaj.
• Botunuzun normal bir mesajına Discord'un yanıtla özelliğiyle verilen ve kullanıcının "ping on reply" ayarının açık olduğu yanıtlar. Bu istisna slash komutu yanıtlarına verilen cevaplar için geçerli değildir.

İşte prefix komutlarının "sessizce" çalışmamasının sebebi budur: bot mesaj olayını alır ama content boş geldiği için ! önekini hiç göremez. discord.py belgesi de bunu açıkça yazar: mention dışı bir prefix ile commands eklentisini kullanıyorsanız Message Content intent'ine ihtiyacınız vardır.

Developer Portal'da intent nasıl açılır?

Privileged intent'i iki yerde etkinleştirmeniz gerekir. Birini unutmak hataya yol açar.

• Developer Portal üzerinde uygulamanızı seçin.
• Sol menüden Bot sekmesine girin.
• Aşağı kaydırıp "Privileged Gateway Intents" bölümünü bulun.
• İhtiyacınız olan anahtarları açın: "Presence Intent", "Server Members Intent", "Message Content Intent". Ardından değişikliği kaydedin.
• Aynı intent'i kodunuzda da isteyin ve botu yeniden başlatın. Intent değişiklikleri yalnızca yeni bir gateway bağlantısında geçerli olur.

discord.js örneği

const { Client, Events, GatewayIntentBits } = require('discord.js');

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent, // privileged: portalda da açık olmalı
  ],
});

client.on(Events.MessageCreate, (message) => {
  if (message.author.bot) return;
  if (message.content === '!ping') message.reply('Pong!');
});

client.login(process.env.DISCORD_TOKEN);

discord.js rehberine göre mesaj almak için Guilds ve GuildMessages, içeriği okumak için ek olarak MessageContent gerekir. Guilds intent'i ayrıca sunucu, kanal ve rol önbelleklerini doldurur; kapalıysa etkileşim ve mesaj verileri yalnızca sunucu ve kanal kimliğini içerir. Hoş geldin mesajı gibi guildMemberAdd olayına dayanan özellikler için GuildMembers gerekir.

discord.py örneği

import os
import discord

intents = discord.Intents.default()
intents.message_content = True  # portalda "Message Content Intent" açık olmalı

client = discord.Client(intents=intents)

@client.event
async def on_message(message):
    if message.author.bot:
        return
    if message.content == '!ping':
        await message.reply('Pong!')

client.run(os.getenv('DISCORD_TOKEN'))

Intents.default() privileged intent'leri açmaz; ihtiyaç duyduklarınızı tek tek True yapmanız gerekir. discord.py ile sıfırdan bot kurmak için discord.py ile bot yapımı rehberine bakabilirsiniz. Token'ı koda yazmamak için .env dosyası kullanın; ayrıntılar bot token güvenliği yazısında.

"Used disallowed intents" hatası (4014)

Kodunuz portalda açık olmayan ya da onaylanmamış bir privileged intent isterse Discord gateway bağlantısını 4014 Disallowed intent(s) kapanış koduyla kapatır. Kütüphaneler bunu farklı biçimlerde gösterir: discord.js [DisallowedIntents] önekli bir hata verir, discord.py ise PrivilegedIntentsRequired istisnası fırlatır. Hatalı hesaplanmış bir bit değeri gönderirseniz bu kez 4013 Invalid intent(s) alırsınız. Discord belgesine göre bu iki kodda da otomatik yeniden bağlanmaya çalışılmamalıdır; önce ayarı düzeltmeniz gerekir.

Çözüm sırası basittir:

• Portalda ilgili anahtarın açık olduğunu kontrol edin.
• Anahtar kilitliyse uygulamanız 10.000 kullanıcı eşiğini geçmiş olabilir; bu durumda inceleme başvurusu gerekir.
• Koddaki intent listesini, gerçekten kullandıklarınızla sınırlayın.
• Botu tamamen kapatıp yeniden başlatın.

Diğer gateway kapanış kodlarının tam tablosu için Discord API hata kodları rehberi yazısına bakın.

Privileged intent'e gerçekten ihtiyacınız var mı?

Discord'un "You Might Not Need a Privileged Intent" rehberi, geliştiricilerin bu intent'leri çoğu zaman alışkanlıktan ya da bir eğitimde öyle gösterildiği için açtığını belirtir. Hem başvuru yükünden kurtulmak hem de kullanıcı verisini azaltmak için önce alternatiflere bakın.

Message Content yerine

• Slash komutları: prefix komutlarının doğrudan yerine geçer; Discord argüman ayrıştırma, doğrulama ve otomatik tamamlamayı sizin için yapar. Bkz. Discord slash komut oluşturma.
• Message context menu komutları: kullanıcı bir mesaja sağ tıklayıp komutu seçtiğinde mesajın tam içeriği size gelir. Çeviri, raporlama, kaydetme gibi "bu mesajla bir şey yap" özellikleri için idealdir.
• Butonlar ve select menüler: anket, rol seçimi, onay ve çok adımlı akışlar için. Bkz. buton, select menu ve modal.
• Modal ve text input: kullanıcının serbest metin yazması gereken formlar için.
• AutoMod API: moderasyon amaçlı içerik taramada Discord'un yerleşik özelliği; rehbere göre AutoMod'un zaten yaptığı işi tekrar etmek tek başına güçlü bir gerekçe sayılmaz. Bkz. Discord AutoMod ve moderasyon botu.

Guild Members yerine

• Kimin aradığınızı biliyorsanız tek üyeyi kimliğiyle getiren Get Guild Member uç noktası.
• Kullanıcı adı veya takma ad önekine göre arama yapan Search Guild Members uç noktası.
• Etkileşim yükündeki üye nesnesi: kullanıcı slash komutu, buton, select menu veya modal kullandığında rolleri, takma adı ve izinleri intent olmadan gelir.

Guild Presences yerine

• Kaç kişinin çevrimiçi olduğunu yaklaşık görmek için sunucu nesnesindeki approximate_presence_count alanı.
• Temel profil bilgisi için Get User uç noktası.
• Botun kendi durumunu ayarlamak bu intent'i gerektirmez.

Sık Sorulan Sorular

Botum mesajları görüyor ama içerik boş geliyor, neden?

Message Content intent'i portalda ya da kodda kapalıdır. Bot mesaj olayını alır ama content, embeds, attachments gibi alanlar boş gelir. Botu etiketlerseniz ya da DM'den yazarsanız içeriğin göründüğünü fark edersiniz; bunlar belgede tanımlı istisnalardır.

Slash komutları için intent gerekir mi?

Hayır. Etkileşim olayları bir intent'e bağlı değildir ve her zaman gönderilir. Etkileşimdeki kullanıcı girdisi de seçenekler (options) olarak gelir, Message Content gerektirmez.

Tüm intent'leri açıp geçsem olmaz mı?

Teknik olarak 10.000 kullanıcı altında privileged intent'leri açabilirsiniz, ancak Discord yalnızca ihtiyaç duyduklarınızı açmanızı ister. Gereksiz intent hem daha fazla olay, bellek ve bant genişliği demektir hem de büyüdüğünüzde inceleme başvurusunda gerekçelendirmeniz gereken bir yük olur.

Portalda açtım ama hâlâ çalışmıyor, ne yapmalıyım?

Intent'i kodda da istediğinizden emin olun ve botu yeniden başlatın; değişiklikler yalnızca yeni bağlantıda geçerli olur. discord.js'te üye listesini çekerken "Members didn't arrive in time" hatası alıyorsanız GuildMembers intent'i eksik olabilir.

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: Discord bot nasıl yapılır · Slash komut oluşturma · Bot doğrulama ve privileged intent · Discord API hata kodları · discord.py ile bot yapımı · AutoMod moderasyon botu · Bot token güvenliği