Discord Embed Mesaj Oluşturma: Alanlar, Sınırlar ve Kod Örnekleri

Embed nesnesinde hangi alanlar var?

Discord API belgesindeki embed yapısı aşağıdaki alanlardan oluşur. Hepsi isteğe bağlıdır; boş bırakmak istediğiniz parçayı hiç göndermemeniz yeterli.

Belgede video ve provider alanları da geçer; ancak mesaj gönderirken embedin type, provider, video alanlarını ve görsellerin height, width, proxy_url değerlerini siz belirleyemezsiniz. Webhook ile gönderilen embedlerin tipi her zaman rich olur. Görsel, footer ikonu ve yazar ikonu adresleri yalnızca http(s) ve ek dosya (attachment) adreslerini kabul eder.

Embed sınırları: belgede yazan rakamlar

Embed, normal mesaj içeriğinin sınırlarına tabi değildir ama kendine özgü sınırları vardır. Belgeye göre tüm sınırlar dahil (inclusive) ölçülür ve baştaki ve sondaki boşluklar otomatik kırpılıp sayılmaz.

Belgede ayrıca şu not var: bir mesajda aynı URL'ye sahip birden fazla embed varsa embedler URL'ye göre tekilleştirilir ve yalnızca ilki gösterilir. Aynı url değerini birden çok embedde kullanıyorsanız bunu aklınızda tutun.

discord.js ile EmbedBuilder kullanımı

discord.js v14, embed oluşturmak için EmbedBuilder sınıfını sunar. Metotlar zincirlenebilir. Aşağıdaki örnek bir slash command yanıtında embed gönderir:

const { EmbedBuilder, Colors } = require('discord.js');

const embed = new EmbedBuilder()
  .setColor(Colors.Blurple)
  .setTitle('Sunucu durumu')
  .setURL('https://example.com/durum')
  .setAuthor({ name: 'Durum Botu' })
  .setDescription('Tüm servisler **çalışıyor**.')
  .addFields(
    { name: 'Gecikme', value: '42 ms', inline: true },
    { name: 'Çalışma süresi', value: '3 gün', inline: true },
  )
  .setTimestamp()
  .setFooter({ text: 'Son kontrol' });

await interaction.reply({ embeds: [embed] });

setColor() bir ColorResolvable kabul eder: tam sayı (0x0099ff), HEX metni, RGB dizisi veya Colors içindeki hazır renkler. Embedi koşullara göre değiştirmek isterseniz zinciri bir değişkene atayıp sonra embed.setColor(...) gibi metotları ayrıca çağırabilirsiniz.

Builder kullanmak zorunda değilsiniz. API'nin beklediği düz nesneyi de gönderebilirsiniz; bu durumda alan adları API'deki gibi icon_url şeklinde yazılır:

await channel.send({
  embeds: [{
    color: 0x0099ff,
    title: 'Sunucu durumu',
    description: 'Tüm servisler çalışıyor.',
    fields: [{ name: 'Gecikme', value: '42 ms', inline: true }],
    footer: { text: 'Son kontrol' },
    timestamp: new Date().toISOString(),
  }],
});

Alınan bir embedi düzenlemek

Embedler değiştirilemez (immutable) nesnelerdir. Var olan bir mesajdaki embedi güncellemek için onu EmbedBuilder.from() ile yeni bir builder'a çevirip mesajı düzenlersiniz:

const eski = message.embeds[0];
const yeni = EmbedBuilder.from(eski).setTitle('Güncellendi');
await message.edit({ embeds: [yeni] });

discord.py ile discord.Embed kullanımı

discord.py 2.x tarafında aynı iş discord.Embed sınıfı ile yapılır. Alanlar add_field(), yazar set_author(), alt bilgi set_footer(), görseller set_image() ve set_thumbnail() ile eklenir. Python ile başlıyorsanız discord.py ile bot yapımı yazısı temel kurulumu anlatıyor.

import discord
from discord import app_commands

@app_commands.command(name='durum', description='Sunucu durumunu gösterir')
async def durum(interaction: discord.Interaction):
    embed = discord.Embed(
        title='Sunucu durumu',
        description='Tüm servisler **çalışıyor**.',
        colour=discord.Colour.blurple(),
        timestamp=discord.utils.utcnow(),
    )
    embed.add_field(name='Gecikme', value='42 ms', inline=True)
    embed.add_field(name='Çalışma süresi', value='3 gün', inline=True)
    embed.set_footer(text='Son kontrol')
    await interaction.response.send_message(embed=embed)

Renkler nasıl verilir?

API seviyesinde color alanı bir tam sayıdır. HEX olarak düşündüğünüz #5865F2 rengini kodda 0x5865F2 şeklinde yazarsınız; bu zaten bir tam sayıdır. discord.js'te Colors.Blurple sabitinin değeri de 0x5865f2'dir. discord.py'de discord.Colour(0x5865F2) veya discord.Colour.blurple() gibi hazır yöntemler kullanılır.

Dosya ekleyip embed içinde göstermek: attachment://

Görseli bir web adresinde barındırmıyorsanız, dosyayı mesajla birlikte yükleyip embed içinde attachment://dosyaadi.png adresiyle gösterebilirsiniz. Discord belgesine göre dosya yükleyen uç noktalar multipart/form-data gövdesi kullanır ve görseller embed içinde attachment://filename adresiyle referans verilebilir. Bu durumda görsel mesajın altında ayrıca değil, embedin içinde görünür.

const { AttachmentBuilder, EmbedBuilder } = require('discord.js');

const dosya = new AttachmentBuilder('./grafik.png');
const embed = new EmbedBuilder()
  .setTitle('Haftalık rapor')
  .setImage('attachment://grafik.png');

await channel.send({ embeds: [embed], files: [dosya] });

file = discord.File('grafik.png', filename='grafik.png')
embed = discord.Embed(title='Haftalık rapor')
embed.set_image(url='attachment://grafik.png')
await channel.send(file=file, embed=embed)

Belgeye göre dosya yükleme sınırı her dosya için geçerlidir ve varsayılan sınır tüm kullanıcılar için 20 MiB'dır; kullanıcının Nitro durumu veya sunucunun Boost seviyesine göre daha yüksek olabilir. Etkileşimlerde bu değer attachment_size_limit alanında size bildirilir.

allowed_mentions ile istenmeyen etiketlemeyi engellemek

Kullanıcıdan gelen metni mesaja koyan botlarda en sık yaşanan sorun, birinin @everyone yazıp botunuz üzerinden herkese bildirim göndermesidir. Bunun çözümü allowed_mentions alanıdır. Belgedeki varsayılanlar şöyle:

• Normal mesajlarda tüm etiket türleri işlenir: {"parse": ["users", "roles", "everyone"]}
• Etkileşim yanıtları ve webhooklarda yalnızca kullanıcı etiketleri işlenir: {"parse": ["users"]}

Tüm etiketlemeleri kapatmak için parse değerini boş dizi yapmanız yeterli. roles ve users dizileri en fazla 100 ID alır. Önemli bir ayrıntı: parse ile aynı türün açık listesi (örneğin hem parse içinde "users" hem de users dizisi) birlikte kullanılmamalıdır; belge bu alanların bu açıdan birbirini dışladığını söyler. Yanıt verirken asıl mesaj sahibini etiketleyip etiketlememeyi replied_user belirler ve varsayılanı false'tur.

// discord.js: hiçbir etiket bildirim üretmesin
await channel.send({
  content: kullaniciMetni,
  allowedMentions: { parse: [] },
});

# discord.py: hiçbir etiket bildirim üretmesin
await channel.send(kullanici_metni, allowed_mentions=discord.AllowedMentions.none())

Embed görünümü için pratik ipuçları

• Alanların yan yana durması için en az iki ardışık alanı inline: true yapmanız gerekir.
• Boş bir ara alan eklemek için discord.js rehberindeki gibi ad ve değer olarak \u200b (sıfır genişlikli boşluk) kullanılabilir.
• Zaman damgası, okuyan kullanıcının cihazındaki saat dilimine göre otomatik gösterilir; saat dönüşümüyle uğraşmayın.
• Discord, mesaj içeriğinden geçersiz unicode gibi bazı karakterleri temizleyebilir. Kullanıcı metnini olduğu gibi göndermeden önce temizleyin.
• Kullanıcıların paylaştığı medyayı yeniden yayınlayan botlar için belge, embed üzerinde içerik taraması bayraklarının (CONTAINS_EXPLICIT_CONTENT gibi) mesaj gönderildikten sonra eklenebileceğini, bu yüzden sonraki Message Update olaylarının da izlenmesi gerektiğini belirtiyor.

Daha zengin, buton ve bölümlerle kurulmuş düzenler istiyorsanız Discord'un yeni bileşen sistemine bakın: Components V2 nedir. Embedin altına buton eklemek içinse buton, select menu ve modal rehberi yazısı işinizi görür.

Sık Sorulan Sorular

Bir mesajda kaç embed gönderebilirim?

Mesaj oluşturma uç noktası en fazla 10 adet rich embed kabul eder. Bu 10 embedin title, description, field.name, field.value, footer.text ve author.name karakterlerinin toplamı da 6000'i geçmemelidir.

Embed açıklaması kaç karakter olabilir?

description en fazla 4096 karakterdir. Başlık 256, alan adı 256, alan değeri 1024, footer metni 2048 karakterle sınırlıdır.

Embed içindeki @etiket neden bildirim göndermiyor?

discord.js rehberinde belirtildiği gibi embed içindeki etiketler bildirim tetiklemez. Birinin bildirim almasını istiyorsanız etiketi mesajın content kısmına yazın ve allowed_mentions ayarının o etikete izin verdiğinden emin olun.

Yerel bilgisayarımdaki görseli embedde nasıl gösteririm?

Dosyayı mesaja ek olarak yükleyin ve embedin image veya thumbnail adresine attachment://dosyaadi.png yazın. discord.js'te AttachmentBuilder, discord.py'de discord.File kullanılır.

Embed mi, Components V2 mi kullanmalıyım?

Basit bilgi kartları için embed hâlâ pratik bir seçenek. Metin, görsel ve butonları serbestçe karıştırmak istiyorsanız Components V2 daha esnektir. İkisinin farkını Components V2 yazısında ayrıntılı anlattık.

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: Slash komut oluşturma · Buton, select menu ve modal · Components V2 nedir · discord.py ile bot yapımı · Discord API hata kodları · Discord webhook ve bot entegrasyonu