WhatsApp şablonuyla mesaj gönderme

Akış

1. Şablon listesini bir kez okuyunKullanacağınız şablonun ref değerini ve gönderebileceği hatları (line_keys) alın.
2. Her işlemde gönderim ucunu çağırınNumara, şablon, değişken değerleri ve varsa dosya bağlantısı. İşlem numaranızı tekrar anahtarı olarak verin.
3. Gerekirse teslim durumunu sorgulayınMesajın iletildiğini ve okunduğunu mesaj listesinden okursunuz.

Temel adres ve anahtarın isteğe nasıl konacağı: Temel adres ve kimlik doğrulama. Anahtarda WhatsApp uygulaması işaretli olmalı.

1. Şablon listesi

Firmanızın bağlı WhatsApp Business hesaplarındaki onaylı şablonları verir. Liste her istekte Meta'dan okunur; yeni onaylanan şablon kendiliğinden görünür. Bu uç ücretsizdir, müşteriye mesaj çıkmaz.

Sorgu parametresi

Örnek yanıt · 200

{
  "templates": [
    {
      "ref": "12:islem_bildirimi",
      "name": "islem_bildirimi",
      "language": "tr",
      "category": "UTILITY",
      "status": "APPROVED",
      "used_by": "SYSTEM",
      "body": "Sayın {{1}}, {{2}} numaralı işleminiz tamamlandı. Tarih: {{3}}.",
      "placeholders": 3,
      "header_format": "IMAGE",
      "line_keys": ["<HAT_ANAHTARI>"],
      "fields": [
        { "slot": "1", "value": "" },
        { "slot": "2", "value": "" },
        { "slot": "3", "value": "" }
      ],
      "needs_place": false
    }
  ],
  "place": ""
}

Kullanacağınız alanlar

2. Gönderim

Numarayla konuşmayı açar (varsa var olanı kullanır) ve şablonu gönderir. Bu uç ücretlidir; bkz. Ücret. Örnek istek sağ sütunda.

Başlıklar

Gövde alanları

Tabloda olmayan bir alan gönderilirse istek 400 BAD_REQUEST ile reddedilir.

media alanları

Değer kuralları

• Bir değer satır sonu ya da sekme içeremez.
• Bir değerde dörtten fazla ardışık boşluk olamaz.
• Değerler yerleştikten sonra metin 1024 karakteri geçemez.

Kurala uymayan istek gönderilmez; 400 TEMPLATE_VALUE_INVALID hangi sıranın neden reddedildiğini söyler.

Başarılı gönderim 200 döner ve açılan konuşmayı verir (sağ sütunda yanıtın bir kısmı). id konuşmanın kimliğidir; kendi kaydınızda işlemle birlikte saklayın, teslim durumunu bununla sorgularsınız.

Teslim ve okunma durumu

Mesajın telefona ulaşıp ulaşmadığını ve okunup okunmadığını sorgulayarak öğrenirsiniz. VeriTakibi bu durum değişikliklerini sizin sisteminize bildirmez; bildirim (itme) yok, gerektiğinde bu ucu çağırırsınız. {id} gönderim yanıtındaki konuşma kimliğidir. Bu uç ücretsizdir.

Yanıt konuşmanın mesajlarını verir. Giden mesajlarda ("direction": "OUT") şu alanlar bulunur:

Örnek yanıt · 200 (kısaltılmış)

{
  "messages": [
    {
      "id": 90211,
      "direction": "OUT",
      "sent_at": "2026-10-12T06:30:05Z",
      "delivered_at": "2026-10-12T06:30:07Z",
      "read_at": "2026-10-12T06:41:52Z",
      "delivery_state": "SENT",
      ...
    }
  ],
  "next_id": 0
}

Tekrar anahtarı

Ağ koptuğunda ya da yanıt gelmediğinde isteği yeniden göndermeniz gerekir. Tekrar anahtarı olmadan her yeniden deneme yeni bir mesaj ve yeni bir ücret demektir. İsteğe bağlı Idempotency-Key başlığı bunu önler.

• Kendi sisteminizdeki işlem numarasını anahtar yapın, örneğin islem-A000123. Aynı işlem için her denemede aynı anahtarı, farklı işlemler için farklı anahtarlar kullanın.
• Anahtar en çok 255 karakterdir ve satır sonu gibi denetim karakteri içeremez; uymayan başlık 400 BAD_REQUEST alır.
• Anahtarlar firmanıza özeldir; başka bir firmanın anahtarıyla çakışmaz.

Gövdeler karşılaştırılırken numaranın yazılışı (+90… ile 90…) ve alanların sırası fark yaratmaz.

Yeniden deneme kuralı

Hatalar

Hata gövdesi bir kod taşır. Bazı kodlarda detail alanı da gelir:

{ "error": "TEMPLATE_VALUE_INVALID", "detail": { "slot": "2", "reason": "unresolved" } }

Ücret

• Her başarılı gönderim ücretlidir.
• Ücret kalemi şablonun kategorisine göre belirlenir: pazarlama, bilgilendirme ya da doğrulama. Kategoriyi Meta verir ve gönderimden sonra bildirir.
• Bakiye kredi limitini aşmışsa gönderim hiç denenmez ve 402 OVER_CREDIT_LIMIT döner.
• Tekrar anahtarıyla yakalanan yeniden deneme ikinci bir ücret yazmaz.
• TEMPLATE_VALUE_INVALID ve TEMPLATE_CHANGED istek Meta'ya çıkmadan verilir; ücret yazılmaz.
• Şablon listesini ve mesaj listesini okumak ücretsizdir.