Mesaj Blokları

Bir mesaj düz metin (body), yapılandırılmış zengin içerik blokları (blocks) veya her ikisini birden taşıyabilir. Bloklar; botların ve temsilcilerin yalnızca düz metin yerine butonlar, kartlar, kaydırmalı listeler, görseller, dosyalar ve çeviriler göndermesini sağlar.

blocks, type alanına göre ayrışan bir ayrımlı birleşim (discriminated union) dizisidir. Her blok nesnesi kendi type değerini bildirir; geri kalan alanlar bu tipe bağlıdır. Makine tarafından okunabilir sözleşme, apps/api/openapi/openapi.yaml içindeki MessageBlock şemasıdır (ve @smaibot/ts-contracts içinde üretilen TypeScript birleşimidir); bu sayfa ise açıklayıcı referanstır.

Blok gönderme

Bloklar, düz mesajlarla aynı uç nokta üzerinden gönderilir:

POST /api/conversations/{conversationId}/messages

{
  "blocks": [
    { "type": "text", "text": "Seçenekleriniz şunlar:" },
    {
      "type": "buttons",
      "buttons": [
        { "title": "Dokümanı aç", "url": "https://example.com/docs" },
        { "title": "Satışla görüş", "payload": "SALES" }
      ]
    }
  ]
}

Bir mesaj; boş olmayan bir body, boş olmayan bir blocks dizisi veya her ikisini içermelidir — ikisini de göndermemek 422 döndürür. Gönderen kimliği her zaman kimliği doğrulanmış temsilciden türetilir, asla istek gövdesinden okunmaz.

Doğrulama

Her blok, iki adımda ayrımlı birleşim olarak doğrulanır:

1. Ayraç (discriminator). type, bilinen blok tiplerinden biri olmalıdır. Bilinmeyen bir tip, blocks.{index}.type üzerinde doğrulama hatası verir.
2. Yük (payload). Bloğun alanları, o tipe özgü kurallara göre doğrulanır. Örneğin bir text bloğu boş olmayan bir text gerektirir; bir image bloğu geçerli bir url gerektirir. Hatalı yük, sorunlu alanda hata verir; örneğin blocks.0.text veya blocks.2.buttons.0.title.

Doğrulama hataları standart 422 ValidationError zarfını kullanır (bkz. Hatalar), böylece istemci her hatayı tam olarak ilgili bloğa ve alana eşleyebilir.

Blok tipleri

Tüm bloklar type ayracını paylaşır. Yük alanları aşağıda listelenmiştir.

text

Düz metin bloğu.

Alan	Tip	Zorunlu	Notlar
text	string	evet	Boş olmayan içerik.

{ "type": "text", "text": "Merhaba" }

buttons

İsteğe bağlı bir text yönlendirmesiyle başlayan bir aksiyon butonları satırı.

Alan	Tip	Zorunlu	Notlar
text	string	hayır	Satırın üstündeki yönlendirme.
buttons	Button[]	evet	En az bir buton.

Bir Button; bir title ile birlikte ya bir url (bağlantı) ya da bir payload (bota geri gönderilen postback) taşır:

Alan	Tip	Zorunlu	Notlar
title	string	evet	Görünen etiket.
url	string	hayır	Bağlantı butonları için geçerli URL.
payload	string	hayır	Bot için postback değeri.

{
  "type": "buttons",
  "text": "Birini seçin",
  "buttons": [
    { "title": "Doküman", "url": "https://example.com" },
    { "title": "Daha fazla", "payload": "MORE" }
  ]
}

card

Başlık ile isteğe bağlı altyazı, görsel ve butonlardan oluşan bir kart.

Alan	Tip	Zorunlu	Notlar
title	string	evet	Boş olmayan.
subtitle	string	hayır
image_url	string	hayır	Geçerli URL.
buttons	Button[]	hayır	Yukarıdakiyle aynı yapı.

{
  "type": "card",
  "title": "Pro plan",
  "subtitle": "İhtiyacınız olan her şey",
  "image_url": "https://example.com/pro.png",
  "buttons": [{ "title": "Yükselt", "payload": "UPGRADE_PRO" }]
}

slider

Yatay olarak kaydırılabilen bir card bloğu galerisi.

Alan	Tip	Zorunlu	Notlar
cards	Card[]	evet	En az bir kart.

{
  "type": "slider",
  "cards": [
    { "type": "card", "title": "Başlangıç" },
    { "type": "card", "title": "Pro", "subtitle": "En popüler" }
  ]
}

image

URL ile referans verilen satır içi bir görsel.

Alan	Tip	Zorunlu	Notlar
url	string	evet	Geçerli URL.
alt	string	hayır	Alt metin.
width	integer	hayır	Piksel.
height	integer	hayır	Piksel.

{ "type": "image", "url": "https://example.com/p.png", "alt": "Ekran görüntüsü" }

file

Bir ek çipi olarak görüntülenen, indirilebilir bir dosya referansı.

Alan	Tip	Zorunlu	Notlar
url	string	evet	Geçerli URL.
filename	string	evet	Boş olmayan.
mime	string	hayır	MIME tipi.
size	integer	hayır	Bayt.

{
  "type": "file",
  "url": "https://example.com/rapor.pdf",
  "filename": "rapor.pdf",
  "mime": "application/pdf",
  "size": 20480
}

translation

Hem orijinal hem de çevrilmiş metni taşıyan bir makine çevirisi.

Alan	Tip	Zorunlu	Notlar
original	string	evet	Kaynak metin.
translated	string	evet	Çevrilmiş metin.
locale	string	evet	Hedef yerel ayar.

{
  "type": "translation",
  "original": "Merhaba",
  "translated": "Hello",
  "locale": "en"
}

Blokların döndürülme şekli

Message kaynağı, blocks alanını gönderildiği yapılandırılmış biçimde, tipli blok modeli üzerinden normalize ederek döndürür — böylece gidiş-dönüş öngörülebilir olur ve bilinmeyen alanlar atılır. Bir mesajın bloğu yoksa blocks, null olur.

Webhook'lar

Giden mesaj webhook'ları, yüklerinde aynı blocks dizisini taşır. Bir tüketici type üzerinde dallanmalı ve tanımadığı her tipe karşı savunmacı davranmalıdır (zamanla yeni blok tipleri eklenebilir).