Discord Intents Nedir ve Nasıl Açılır?

Discord intents, botunuzun Discord ağ geçidinden (gateway) hangi olay türlerini almak istediğini önceden bildirdiği bir abonelik sistemidir. Bot ilk bağlandığında "ben şu olaylarla ilgileniyorum" der ve Discord yalnızca o olayları gönderir. Doğru intent'leri açmazsanız botunuz ya hiç çalışmaz ya da bazı olaylar (örneğin yeni üye katılması veya mesaj içeriği) hiçbir zaman gelmez. Bu yazıda intent'lerin ne olduğunu, privileged (ayrıcalıklı) intent'lerin neden farklı olduğunu ve hem Developer Portal'da hem kodda bunları nasıl doğru ayarlayacağınızı anlatıyorum.

Intent nedir ve neden var?

Bir Discord botu, gateway adı verilen kalıcı bir WebSocket bağlantısı üzerinden gerçek zamanlı olaylar alır: mesaj gönderildi, üye katıldı, kanal güncellendi, tepki eklendi ve onlarca farklı olay. Büyük sunucularda bu trafik çok yoğun olabilir. Intent'ler, botun gerçekten ilgilendiği olay gruplarını seçmesini sağlar; böylece hem Discord'un yükü hem de botunuzun işlemesi gereken veri azalır.

Her intent, ilgili olayların bir paketine karşılık gelir. Örneğin Guilds intent'i sunucu, kanal ve rol olaylarını; GuildMessages intent'i mesaj gönderme/silme olaylarını kapsar. Bir intent'i açmazsanız, o gruba ait olaylar botunuza hiç ulaşmaz ve ilgili dinleyicileriniz (event listener) sessizce çalışmaz.

Normal intent'ler ve privileged intent'ler

Intent'ler iki kategoriye ayrılır. Çoğu intent standarttır ve kodda istemeniz yeterlidir; ek bir onay gerekmez. Ancak üç intent privileged (ayrıcalıklı) olarak işaretlenmiştir çünkü hassas veriye erişim sağlarlar:

• Server Members Intent (GuildMembers): üye katılma/ayrılma olayları ve tam üye listesi.
• Presence Intent (GuildPresences): kullanıcıların çevrimiçi/çevrimdışı durumu ve oynadığı oyun gibi presence bilgileri.
• Message Content Intent (MessageContent): mesajların gerçek metin içeriği, ekleri ve embed'leri.

Bu üçü, hem Developer Portal'da bir anahtarla açılmalı hem de kodda istenmelidir. Eğer kodda istediğiniz bir privileged intent'i portalda açmadıysanız, bot bağlanmaya çalışırken Used disallowed intents hatasıyla kapanır.

Developer Portal'da privileged intent'leri açma

Privileged intent'leri açmak için şu adımları izleyin:

• Discord Developer Portal'a gidip uygulamanızı seçin.
• Sol menüden Bot sekmesine geçin.
• Privileged Gateway Intents başlığı altındaki anahtarları bulun: Presence Intent, Server Members Intent ve Message Content Intent.
• Botunuzun ihtiyaç duyduğu intent'leri açın ve Save Changes ile kaydedin.

Önemli bir kısıtlama: botunuz 100'den fazla sunucuda bulunuyorsa, privileged intent'leri kullanabilmek için botun doğrulanması (verification) ve her privileged intent için ayrı onay almanız gerekir. 100 sunucunun altındaki botlar onaysız kullanabilir. Bu yüzden gerçekten ihtiyacınız olmayan privileged intent'leri açmayın; ileride ölçeklenmeyi zorlaştırır.

discord.js'te intent'leri tanımlama

discord.js v14'te intent'ler GatewayIntentBits enum'u üzerinden Client oluşturulurken verilir. Sadece ihtiyaç duyduğunuz intent'leri ekleyin:

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

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,   // privileged
    GatewayIntentBits.GuildMembers      // privileged
  ]
});

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

client.login(process.env.DISCORD_TOKEN);

Burada dikkat edilecek klasik bir tuzak şudur: MessageContent intent'ini açmazsanız message.content alanı çoğu mesajda boş gelir. Botunuz komutlara cevap vermiyor gibi görünür ama aslında sorun mesajın metnini hiç görememesidir. Bot'un kendi mention'landığı mesajlar ve DM'ler bu kuralın dışındadır, ama prefix tabanlı komutlar için bu intent şarttır.

discord.py'de intent'leri tanımlama

Python tarafında mantık aynıdır; discord.Intents nesnesini yapılandırıp Client veya commands.Bot'a verirsiniz:

import discord
from discord.ext import commands

intents = discord.Intents.default()
intents.message_content = True   # privileged
intents.members = True           # privileged

bot = commands.Bot(command_prefix='!', intents=intents)

@bot.event
async def on_ready():
    print(f'Giriş yapıldı: {bot.user}')

bot.run('TOKEN')

İhtiyacınız varsa discord.Intents.all() ile hepsini açabilirsiniz, ama bu kötü bir alışkanlıktır: portalda açık olmayan bir privileged intent'i istediğiniz an bot çöker ve gereksiz veri trafiği oluşur. En az ayrıcalık ilkesini izleyin ve yalnızca gerçekten kullandığınız intent'leri açın.

Intent'leri izinlerle (permissions) karıştırmayın

Sık yapılan bir kafa karışıklığı, intent'leri sunucu izinleriyle aynı şey sanmaktır. İkisi farklı katmanlardır:

• Intent'ler botun gateway'den hangi olayları alacağını belirler; bu, uygulamanız genelinde tanımlanır.
• İzinler (permissions) botun bir sunucuda ne yapabileceğini belirler; bunlar rol ve kanal düzeyinde verilir (mesaj gönderme, kanal yönetme, üye atma gibi).

Örneğin GuildMembers intent'i açık olsa bile bot, "Kick Members" izni olmadan üye atamaz. Tersine, bota tüm izinleri verseniz de doğru intent açık değilse ilgili olayları hiç görmez. Sağlıklı bir bot kurulumu, gerekli intent'leri kodda istemek ve sunucuya davet bağlantısını (OAuth2 URL) yalnızca gereken izin kapsamıyla oluşturmaktan geçer.

Sık Sorulan Sorular

Botum komutlara cevap vermiyor, mesaj içeriği boş geliyor. Neden?

Büyük ihtimalle Message Content Intent kapalıdır. Hem Developer Portal'daki Bot sekmesinden açın hem de kodda MessageContent / message_content intent'ini ekleyin. Bu intent olmadan prefix tabanlı komutlar çalışmaz; slash komutları ise içerik intent'ine ihtiyaç duymadan çalışmaya devam eder.

"Used disallowed intents" hatası alıyorum.

Bu hata, kodda istediğiniz bir privileged intent'in Developer Portal'da açık olmadığını gösterir. Hata mesajındaki intent'i portaldan açıp kaydedin veya gerçekten kullanmıyorsanız kod tarafından kaldırın.

Hangi intent'leri açmalıyım?

Yalnızca botunuzun işlevi için gerekenleri. Neredeyse her bot Guilds intent'ine ihtiyaç duyar. Prefix komutları için MessageContent, hoş geldin/güle güle sistemleri için GuildMembers, presence takibi için GuildPresences ekleyin. Gerekmeyen privileged intent'leri kapalı tutmak hem güvenlik hem de 100+ sunucu doğrulaması açısından daha iyidir.

Botunuzu doğru intent ve izinlerle sağlam kurmak mı istiyorsunuz? Discord botu mimarisi, intent yapılandırması ve dağıtım konusunda yardıma ihtiyacınız olursa benimle iletişime geçin.