Bildirimler (webhook)

Gönderilen mesajlar, mesaj durumları ve gelen mesajlar, tanımladığınız bildirim adresine POST ile iletilir. Bu API'de webhook için bir işlem yoktur: adres portaldan tanımlanır, WhatsApp → Ayarlar → Yeni Webhook Ekle.

Üç tür bildirim vardır:

Bildirim	Ne zaman	Tanıma
Gönderilen mesaj	Her gönderimde bir kez	type alanı ve to
Mesaj durumu	Mesajın durumu değiştikçe	status alanı
Gelen mesaj	Kişi size yazdığında	from_user_id alanı

• Mesaj durumu, gönderilen mesaja id alanıyla (wamid.…) bağlanır.
• Kişi her zaman from_user_id / recipient_user_id (TR.…) ile tanınır. Numarasını gizleyen kişide numara alanları boş gelebilir.
• timestamp Unix zamanıdır (saniye), metin olarak gelir.
• Bazı bildirimlerde burada anlatılmayan ek alanlar bulunabilir; bunlar yok sayılabilir.

Gönderilen mesaj

Her gönderimde bir kez gelir. type gönderilen türdür: text, template, image, video, audio, document, location, reaction.

Metin:

{
  "id": "wamid.HBgMOTA1MzIxMTIzNDU2FQIAERgS…",
  "from": "908501234567",
  "to": "+905321234567",
  "timestamp": "1793782405",
  "type": "text",
  "text": {
    "body": "Merhaba, siparişiniz hazır."
  }
}

Şablon (body şablonun kayıtlı metnidir, değişkenler {{1}} olarak kalır):

{
  "id": "wamid.HBgMOTA1MzIxMTIzNDU2FQIAERgS…",
  "from": "908501234567",
  "to": "+905321234567",
  "timestamp": "1793782405",
  "type": "template",
  "template": {
    "name": "netgsm_verify_code",
    "language": "tr",
    "body": " Doğrulama kodunuz: *{{1}}*. Güvenliğiniz için bu kodu paylaşmayın.   Süresi 5 dakika sonra doluyor. "
  }
}

Görsel (video aynı, type: "video"):

{
  "id": "wamid.HBgMOTA1MzIxMTIzNDU2FQIAERgS…",
  "from": "908501234567",
  "to": "+905321234567",
  "timestamp": "1793782405",
  "type": "image",
  "image": {
    "id": "1127655490006281",
    "caption": "Ürün fotoğrafı",
    "link": "https://ornek.com/urun.jpg"
  }
}

Mesaj durumu

status: sent (gönderildi), delivered (iletildi), read (okundu), failed (gönderilemedi). pricing, Meta'nın bu mesaj için bildirdiği ücret kategorisidir.

{
  "id": "wamid.HBgMOTA1MzIxMTIzNDU2FQIAERgS…",
  "status": "delivered",
  "timestamp": "1793782407",
  "recipient_id": "905321234567",
  "recipient_user_id": "TR.1234567890123456",
  "pricing": {
    "billable": true,
    "pricing_model": "PMP",
    "category": "authentication",
    "type": "regular"
  }
}

Gönderilemeyen mesaj (errors sebebi verir):

{
  "id": "wamid.HBgMOTA1MzIxMTIzNDU2FQIAERgS…",
  "status": "failed",
  "timestamp": "1793782407",
  "recipient_id": "905321234567",
  "errors": [
    {
      "code": 131026,
      "title": "Message undeliverable",
      "message": "Message undeliverable",
      "error_data": {
        "details": "Message Undeliverable."
      }
    }
  ]
}

Gelen mesaj

Kişinin gönderdiği mesaj, Meta'nın gönderdiği biçimde gelir.

Metin:

{
  "from": "905321234567",
  "from_user_id": "TR.1234567890123456",
  "id": "wamid.HBgMOTA1MzIxMjM0NTY3FQIAEhgU…",
  "timestamp": "1793782410",
  "type": "text",
  "text": {
    "body": "Teşekkürler"
  }
}

Görsel, video, ses, belge, çıkartma (url Meta'nın indirme bağlantısıdır, kısa sürelidir):

{
  "from": "905321234567",
  "from_user_id": "TR.1234567890123456",
  "id": "wamid.HBgMOTA1MzIxMjM0NTY3FQIAEhgU…",
  "timestamp": "1793782410",
  "type": "document",
  "document": {
    "filename": "Dekont.pdf",
    "mime_type": "application/pdf",
    "sha256": "MlIg6wRlkOdUNIP92F1Y…",
    "id": "1433099308896482",
    "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=…"
  }
}

Şablondaki hızlı yanıt düğmesine basılması (context.id düğmenin bulunduğu mesajdır):

{
  "from": "905321234567",
  "from_user_id": "TR.1234567890123456",
  "id": "wamid.HBgMOTA1MzIxMjM0NTY3FQIAEhgU…",
  "timestamp": "1793782410",
  "type": "button",
  "button": {
    "payload": "Evet",
    "text": "Evet"
  },
  "context": {
    "from": "908501234567",
    "id": "wamid.HBgMOTA1MzIxMTIzNDU2FQIAERgS…"
  }
}

Mesaja tepki:

{
  "from": "905321234567",
  "from_user_id": "TR.1234567890123456",
  "id": "wamid.HBgMOTA1MzIxMjM0NTY3FQIAEhgU…",
  "timestamp": "1793782410",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.HBgMOTA1MzIxMTIzNDU2FQIAERgS…",
    "emoji": "👍"
  }
}

Konum (location), kişi kartı (contacts) ve liste / düğme seçimi (interactive) de aynı biçimde, Meta'nın alanlarıyla gelir. Bir mesaja cevap olarak yazılan ya da iletilen mesajda context alanı bulunur (forwarded: true iletilmiş mesaj).