İçeriğe geç
Veri MerkeziVeri MerkeziAPI

API referansı

Şablon, metin, medya, konum, kişi kartı, tepki ve form mesajı gönderin; gelen mesajları okundu işaretleyin ve kaçan olayları mesaj kayıtlarından geri alın.

#Message nesnesi

  • idinteger
    Veri Merkezi'deki mesaj kaydının kimliği.
  • wamidstring
    WhatsApp mesaj kimliği. Test anahtarıyla gönderilenlerde test. ile başlar.
  • directionstring
    Yön. echo, işletmenin telefondaki WhatsApp Business uygulamasından yazdığı mesajdır.Değerler: inbound, outbound, echo
  • typestring
    Mesaj türü (ör. text, template, image, video, audio, document, sticker, reaction, interactive, button, location, contacts).
  • statusstring
    Mesaj durumu (ör. received, sent, delivered, read, failed).
  • fromstring · boş olabilir
    Gönderen telefon numarası.
  • tostring · boş olabilir
    Alıcı telefon numarası.
  • user_idstring · boş olabilir
    Karşı tarafın BSUID değeri (telefonu görünmeyen kullanıcılar).
  • usernamestring · boş olabilir
    Gönderenin WhatsApp kullanıcı adı.
  • textstring · boş olabilir
    Mesaj metni; medyada açıklama.
  • mediaobject · boş olabilir
    Medya bilgisi; gelen medyada media_id ile indirilir.
  • template_namestring · boş olabilir
    Şablon mesajlarında şablon adı.
  • campaign_idinteger · boş olabilir
    Kampanyadan gönderildiyse kampanya kimliği.
  • is_testboolean
    Test anahtarıyla oluşturulan kayıt mı.
  • errorobject · boş olabilir
    Başarısız mesajda code, title, message.
  • created_atstring
    Oluşturulma zamanı (ISO 8601).
  • sent_atstring · boş olabilir
    Gönderim zamanı.
  • delivered_atstring · boş olabilir
    Teslim zamanı.
  • read_atstring · boş olabilir
    Okunma zamanı.
  • failed_atstring · boş olabilir
    Başarısızlık zamanı.
  • contextobject · boş olabilir
    Alıntılı mesajda { message_id, from, forwarded, frequently_forwarded }.
  • reactionobject · boş olabilir
    Tepki mesajında { message_id, emoji }.
  • locationobject · boş olabilir
    Konum mesajında { latitude, longitude, name, address, url }.
  • contactsarray · boş olabilir
    Kişi kartı paylaşıldıysa Meta'nın kişi dizisi.
  • original_message_idstring · boş olabilir
    Silme/düzenlemede hedef mesajın wamid değeri.
  • buttonobject · boş olabilir
    Buton yanıtında { payload, text }.
Message nesnesi
{
  "id": 248117,
  "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAEhggQTNFQkQ2RjQ3MEIyQzk0RTE4AA==",
  "direction": "inbound",
  "type": "text",
  "status": "received",
  "from": "905550000000",
  "to": null,
  "user_id": null,
  "username": null,
  "text": "Merhaba, siparişim ne durumda?",
  "media": null,
  "template_name": null,
  "campaign_id": null,
  "is_test": false,
  "error": null,
  "created_at": "2026-10-10T10:00:00+03:00",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "failed_at": null,
  "context": null,
  "reaction": null,
  "location": null,
  "contacts": null,
  "original_message_id": null,
  "button": null
}

#Şablon mesajı gönder

POST/messages
Meta onaylı bir şablonla mesaj gönderir. Müşteri size son 24 saat içinde yazmadıysa yalnız şablon mesajı gönderebilirsiniz. Kapsam: messages:send
Canlı anahtarda her başarılı gönderim 1 kredi düşer. Kredi gönderimden önce ayrılır; gönderim başarısız olursa iade edilir.
Test anahtarıyla (vmk_test_) mesaj Meta'ya gönderilmez: simulated: true, credits_used: 0 ve test. ile başlayan sahte bir wamid döner.
Gönderim hatalarında hata nesnesi ayrıca retryable (bool), meta_code ve meta_subcode alanlarını taşır.
Dinamik URL butonunda parameters[0].text, şablon adresinin sonundaki {{1}} yerine geçer. Meta kuralı gereği tek değişken olur ve adresin sonunda yer alır.
OTP için template.otp alanına kodu vermeniz yeterlidir; ya da gövde parametresi ile sub_type: "url", index: 0 buton parametresine aynı kodu açıkça verin.
Form (FLOW) butonu: { "type": "button", "sub_type": "flow", "index": 0, "parameters": [{ "type": "action", "flow_token": "...", "flow_action_data": {} }] }. Meta'nın kendi biçimi de kabul edilir.
2.25.0: Şablon Veri Merkezi'nde kayıtlıysa ve medya başlıklıysa (IMAGE / VIDEO / DOCUMENT), header bileşeni göndermediğinizde kayıtlı medya kalıcı bağlantısıyla (GET /templates yanıtındaki header_media.url) otomatik eklenir; her gönderimde dosya seçtirmenize gerek yoktur. header gönderirseniz hiçbir şey eklenmez, sizinki aynen gider.
2.25.0: Dinamik URL butonu gönderimi: components: [{ "type": "button", "sub_type": "url", "index": "0", "parameters": [{ "type": "text", "text": "<adres sonu>" }] }]. Sabit adresli URL butonuna button bileşeni gönderilmez (Meta 132000 / 131008 ailesiyle reddeder). Ayrıca AUTHENTICATION hariç, şablon Veri Merkezi'nde kayıtlıysa bileşenler tanımla karşılaştırılır; uyumsuzlukta Meta'ya gitmeden 422 invalid_template_parameters döner (field: template.components[0].parameters, template.components[0].index ya da template.components). Şablon Veri Merkezi'nde kayıtlı değilse istek aynen iletilir.

Başlıklar

  • Idempotency-Keyisteğe bağlı
    Önerilir. 8–128 karakter. Aynı anahtar + aynı gövde ilk yanıtı döndürür (mesaj ikinci kez gitmez); aynı anahtar + farklı gövde 422 idempotency_key_conflict döner. 24 saat saklanır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Gönderimi yapacak numaranızın Meta kimliği. Numara size ait ve aktif olmalıdır.
  • tostringzorunlu
    Alıcının telefon numarası, uluslararası biçimde ve + olmadan (ör. 905550000000). Rakam dışı karakterler atılır; en az 10 hane gerekir. Telefonu olmayan alıcıda to yerine recipient gönderin.
  • recipientstringisteğe bağlı
    Telefonu görünmeyen kullanıcının WhatsApp kullanıcı kimliği (BSUID, webhook'taki user_id). Yalnız to boşken kullanılır. Eş anlamlıları: recipient_id, bsuid.
  • contextobjectisteğe bağlı
    Alıntılı yanıt. Alıcıda yanıtladığınız mesaj alıntı balonuyla görünür. Tepki mesajıyla birlikte kullanılamaz.
    Alt alanları göster
    • message_idstringzorunlu
      Yanıtlanan mesajın wamid değeri (webhook'taki data.wamid).
  • biz_opaque_callback_datastringisteğe bağlı
    En fazla 512 karakterlik kendi eşleştirme değeriniz. message.status.* olaylarında data.biz_opaque_callback_data olarak aynen döner. Göndermezseniz ve Idempotency-Key verdiyseniz sunucu bu alanı anahtarın değeriyle kendisi doldurur.
  • typestringisteğe bağlı
    template (önerilir; şablon mesajında isteğe bağlıdır).Değerler: template
  • templateobjectzorunlu
    Onaylı şablon. Şablon, gönderen numaranın bağlı olduğu WABA'da APPROVED olmalıdır.
    Alt alanları göster
    • namestringzorunlu
      Şablon adı (küçük harf, rakam, alt çizgi).
    • languagestring | objectzorunlu
      Şablonun onaylandığı dil kodu. "tr" ya da Meta biçimi { "code": "tr" } kabul edilir.Varsayılan: tr
    • componentsarrayisteğe bağlı
      Meta bileşen nesneleri. Gövde değişkenleri için body; dinamik URL butonu için { "type": "button", "sub_type": "url", "index": "0", "parameters": [{ "type": "text", "text": "<adres sonu>" }] } (index düğme sırası, sayı ya da metin); form butonu için sub_type: "flow". Medya başlıklı şablonda header bileşenini göndermeyebilirsiniz: kayıtlı başlık medyası kalıcı bağlantıyla otomatik eklenir; header gönderirseniz aynen kullanılır. Sabit adresli URL butonuna button bileşeni GÖNDERİLMEZ.
    • otpstringisteğe bağlı
      AUTHENTICATION şablonları için kolaylık alanı. Yalnız kodu verin; gövde ve kod butonu Meta kuralına uygun otomatik kurulur. components gönderilirse yok sayılır.

Hatalar

DurumKodNe zaman
402insufficient_creditsMesaj krediniz yetersiz. Yanıtta error.balance döner.
403insufficient_scopeAnahtarda messages:send kapsamı yok.
404number_not_foundNumara size ait değil ya da aktif değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
409meta_outcome_unknownİstek Meta'ya iletildi ama sonucu doğrulanamadı. Aynı anahtarla tekrar göndermeyin; durum olayını bekleyin (retryable: false).
409idempotency_in_progressAynı Idempotency-Key ile bir istek hâlâ işleniyor.
422invalid_requestZorunlu alan eksik ya da biçim hatalı (error.field alanı belirtir).
422invalid_phoneAlıcı numarası geçersiz (en az 10 hane).
422idempotency_key_conflictAynı anahtar farklı bir gövdeyle kullanılmış.
422meta_send_failedMeta gönderimi reddetti. meta_code ve meta_subcode alanlarına bakın (retryable: true).
500send_failedSistem hatası; kredi iade edildi. Tekrar deneyebilirsiniz.
422template_not_in_wabaŞablon gönderen numaranın WABA'sında yok ya da onaylı değil (Meta 132001; retryable: false).
422invalid_template_flow_buttonŞablondaki form butonu parametresi hatalı.
422invalid_template_parametersDüğme bileşeni kayıtlı şablon tanımına uymuyor: sabit adresli URL butonuna parametre verilmiş (template.components[i].parameters), index'teki düğme URL değil ya da index eksik (template.components[i].index), değişkenli URL butonu için parametre yok (template.components). Meta'ya gönderilmez.
curl -X POST "https://api.verimerkezi.app/wa/messages" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "905550000000",
    "type": "template",
    "template": {
      "name": "siparis_onayi",
      "language": {
        "code": "tr"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Ahmet"
            },
            {
              "type": "text",
              "text": "VM-2026-1234"
            }
          ]
        }
      ]
    }
  }'
Yanıt 201
{
  "ok": true,
  "id": 48213,
  "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAERgSMUI4QzY3RDFFNzBBNDlGRTlBAA==",
  "to": "905550000000",
  "type": "template",
  "status": "sent",
  "mode": "live",
  "simulated": false,
  "credits_used": 1,
  "balance": 9875
}

#Metin mesajı gönder

POST/messages
Serbest metin mesajı gönderir. Yalnız müşteri size son 24 saat içinde yazdıysa teslim edilir; aksi hâlde Meta reddeder. Kapsam: messages:send
Canlı anahtarda her başarılı gönderim 1 kredi düşer. Kredi gönderimden önce ayrılır; gönderim başarısız olursa iade edilir.
Test anahtarıyla (vmk_test_) mesaj Meta'ya gönderilmez: simulated: true, credits_used: 0 ve test. ile başlayan sahte bir wamid döner.
Gönderim hatalarında hata nesnesi ayrıca retryable (bool), meta_code ve meta_subcode alanlarını taşır.
Pencere kapalıyken gönderim 422 meta_send_failed ve meta_code: 131047 döner. Bu durumda şablon kullanın.
text.preview_url: true gönderilirse metindeki bağlantının önizlemesi gösterilir; gönderilmezse önizleme kapalıdır.
Alıntılı yanıtta Meta, alıntılanan mesaj 30 günden eskiyse alıntı balonunu göstermeyebilir.

Başlıklar

  • Idempotency-Keyisteğe bağlı
    Önerilir. 8–128 karakter. Aynı anahtar + aynı gövde ilk yanıtı döndürür (mesaj ikinci kez gitmez); aynı anahtar + farklı gövde 422 idempotency_key_conflict döner. 24 saat saklanır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Gönderimi yapacak numaranızın Meta kimliği. Numara size ait ve aktif olmalıdır.
  • tostringzorunlu
    Alıcının telefon numarası, uluslararası biçimde ve + olmadan (ör. 905550000000). Rakam dışı karakterler atılır; en az 10 hane gerekir. Telefonu olmayan alıcıda to yerine recipient gönderin.
  • recipientstringisteğe bağlı
    Telefonu görünmeyen kullanıcının WhatsApp kullanıcı kimliği (BSUID, webhook'taki user_id). Yalnız to boşken kullanılır. Eş anlamlıları: recipient_id, bsuid.
  • contextobjectisteğe bağlı
    Alıntılı yanıt. Alıcıda yanıtladığınız mesaj alıntı balonuyla görünür. Tepki mesajıyla birlikte kullanılamaz.
    Alt alanları göster
    • message_idstringzorunlu
      Yanıtlanan mesajın wamid değeri (webhook'taki data.wamid).
  • biz_opaque_callback_datastringisteğe bağlı
    En fazla 512 karakterlik kendi eşleştirme değeriniz. message.status.* olaylarında data.biz_opaque_callback_data olarak aynen döner. Göndermezseniz ve Idempotency-Key verdiyseniz sunucu bu alanı anahtarın değeriyle kendisi doldurur.
  • typestringisteğe bağlı
    text (önerilir; metin mesajında isteğe bağlıdır).Değerler: text
  • textobject | stringzorunlu
    Mesaj metni: { "body": "..." } nesnesi ya da düz metin. Nesnede body metin değilse 422 invalid_request (field: text). Yalnız 24 saatlik müşteri hizmet penceresi açıkken teslim edilir.
    Alt alanları göster
    • bodystringzorunlu
      Mesaj metni.
    • preview_urlbooleanisteğe bağlı
      true gönderilirse metindeki bağlantının önizlemesi gösterilir. Varsayılan: kapalı.

Hatalar

DurumKodNe zaman
402insufficient_creditsMesaj krediniz yetersiz. Yanıtta error.balance döner.
403insufficient_scopeAnahtarda messages:send kapsamı yok.
404number_not_foundNumara size ait değil ya da aktif değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
409meta_outcome_unknownİstek Meta'ya iletildi ama sonucu doğrulanamadı. Aynı anahtarla tekrar göndermeyin; durum olayını bekleyin (retryable: false).
409idempotency_in_progressAynı Idempotency-Key ile bir istek hâlâ işleniyor.
422invalid_requestZorunlu alan eksik ya da biçim hatalı (error.field alanı belirtir).
422invalid_phoneAlıcı numarası geçersiz (en az 10 hane).
422idempotency_key_conflictAynı anahtar farklı bir gövdeyle kullanılmış.
422meta_send_failedMeta gönderimi reddetti. meta_code ve meta_subcode alanlarına bakın (retryable: true).
500send_failedSistem hatası; kredi iade edildi. Tekrar deneyebilirsiniz.
422invalid_contextcontext.message_id geçerli bir wamid değil.
curl -X POST "https://api.verimerkezi.app/wa/messages" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "905550000000",
    "type": "text",
    "text": {
      "body": "Merhaba Ahmet Bey, siparişiniz kargoya verildi."
    },
    "context": {
      "message_id": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAEhggQTNFQkQ2RjQ3MEIyQzk0RTE4AA=="
    }
  }'
Yanıt 201
{
  "ok": true,
  "id": 48213,
  "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAERgSMUI4QzY3RDFFNzBBNDlGRTlBAA==",
  "to": "905550000000",
  "type": "text",
  "status": "sent",
  "mode": "live",
  "simulated": false,
  "credits_used": 1,
  "balance": 9875
}

#Medya mesajı gönder

POST/messages
Görsel, video, ses, belge ya da çıkartma gönderir. Medyayı herkese açık bir https adresiyle (link) ya da POST /media ile aldığınız kimlikle (id) verin. Serbest mesaj olduğu için 24 saatlik pencere kuralı geçerlidir. Kapsam: messages:send
Canlı anahtarda her başarılı gönderim 1 kredi düşer. Kredi gönderimden önce ayrılır; gönderim başarısız olursa iade edilir.
Test anahtarıyla (vmk_test_) mesaj Meta'ya gönderilmez: simulated: true, credits_used: 0 ve test. ile başlayan sahte bir wamid döner.
Gönderim hatalarında hata nesnesi ayrıca retryable (bool), meta_code ve meta_subcode alanlarını taşır.
Meta sınırları: görsel 5 MB (JPEG, PNG), video 16 MB (MP4, 3GPP), ses 16 MB, belge 100 MB, çıkartma (WebP) 500 KB.
Sesli not için OGG/Opus dosyayı POST /media ile yükleyip "audio": { "id": "...", "voice": true } gönderin.

Başlıklar

  • Idempotency-Keyisteğe bağlı
    Önerilir. 8–128 karakter. Aynı anahtar + aynı gövde ilk yanıtı döndürür (mesaj ikinci kez gitmez); aynı anahtar + farklı gövde 422 idempotency_key_conflict döner. 24 saat saklanır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Gönderimi yapacak numaranızın Meta kimliği. Numara size ait ve aktif olmalıdır.
  • tostringzorunlu
    Alıcının telefon numarası, uluslararası biçimde ve + olmadan (ör. 905550000000). Rakam dışı karakterler atılır; en az 10 hane gerekir. Telefonu olmayan alıcıda to yerine recipient gönderin.
  • recipientstringisteğe bağlı
    Telefonu görünmeyen kullanıcının WhatsApp kullanıcı kimliği (BSUID, webhook'taki user_id). Yalnız to boşken kullanılır. Eş anlamlıları: recipient_id, bsuid.
  • contextobjectisteğe bağlı
    Alıntılı yanıt. Alıcıda yanıtladığınız mesaj alıntı balonuyla görünür. Tepki mesajıyla birlikte kullanılamaz.
    Alt alanları göster
    • message_idstringzorunlu
      Yanıtlanan mesajın wamid değeri (webhook'taki data.wamid).
  • biz_opaque_callback_datastringisteğe bağlı
    En fazla 512 karakterlik kendi eşleştirme değeriniz. message.status.* olaylarında data.biz_opaque_callback_data olarak aynen döner. Göndermezseniz ve Idempotency-Key verdiyseniz sunucu bu alanı anahtarın değeriyle kendisi doldurur.
  • typestringzorunlu
    Medya türü.Değerler: image, video, audio, document, sticker
  • image | video | audio | document | stickerobjectzorunlu
    type ile aynı adlı medya nesnesi.
    Alt alanları göster
    • linkstringisteğe bağlı
      Herkese açık https:// adresi. link ya da id zorunludur; ikisi birden verilirse link kullanılır.
    • idstringisteğe bağlı
      POST /media ile aldığınız Meta medya kimliği (30 gün geçerli).
    • captionstringisteğe bağlı
      Görünen açıklama. Yalnız image, video, document.
    • filenamestringisteğe bağlı
      Alıcıda görünen dosya adı. Yalnız document.
    • voicebooleanisteğe bağlı
      Yalnız audio. true ise sesli not olarak gider (OGG/Opus). Verilmezse .ogg/.opus bağlantı ya da audio/ogg medya otomatik sesli not olur.

Hatalar

DurumKodNe zaman
402insufficient_creditsMesaj krediniz yetersiz. Yanıtta error.balance döner.
403insufficient_scopeAnahtarda messages:send kapsamı yok.
404number_not_foundNumara size ait değil ya da aktif değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
409meta_outcome_unknownİstek Meta'ya iletildi ama sonucu doğrulanamadı. Aynı anahtarla tekrar göndermeyin; durum olayını bekleyin (retryable: false).
409idempotency_in_progressAynı Idempotency-Key ile bir istek hâlâ işleniyor.
422invalid_requestZorunlu alan eksik ya da biçim hatalı (error.field alanı belirtir).
422invalid_phoneAlıcı numarası geçersiz (en az 10 hane).
422idempotency_key_conflictAynı anahtar farklı bir gövdeyle kullanılmış.
422meta_send_failedMeta gönderimi reddetti. meta_code ve meta_subcode alanlarına bakın (retryable: true).
500send_failedSistem hatası; kredi iade edildi. Tekrar deneyebilirsiniz.
422invalid_medialink/id yok, bağlantı https:// ile başlamıyor ya da audio.voice boolean değil.
curl -X POST "https://api.verimerkezi.app/wa/messages" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "905550000000",
    "type": "document",
    "document": {
      "link": "https://cdn.example.com/fatura-2026-10.pdf",
      "filename": "fatura-2026-10.pdf",
      "caption": "Ekim ayı faturanız ektedir."
    }
  }'
Yanıt 201
{
  "ok": true,
  "id": 48213,
  "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAERgSMUI4QzY3RDFFNzBBNDlGRTlBAA==",
  "to": "905550000000",
  "type": "document",
  "status": "sent",
  "mode": "live",
  "simulated": false,
  "credits_used": 1,
  "balance": 9875
}

#Konum mesajı gönder

POST/messages
Haritada açılan bir konum gönderir. Serbest mesajdır: yalnız 24 saatlik müşteri hizmet penceresi açıkken teslim edilir. Kapsam: messages:send
Canlı anahtarda her başarılı gönderim 1 kredi düşer. Kredi gönderimden önce ayrılır; gönderim başarısız olursa iade edilir.
Test anahtarıyla (vmk_test_) mesaj Meta'ya gönderilmez: simulated: true, credits_used: 0 ve test. ile başlayan sahte bir wamid döner.
Gönderim hatalarında hata nesnesi ayrıca retryable (bool), meta_code ve meta_subcode alanlarını taşır.
GET /messages kaydının text alanında ve panel gelen kutusunda okunur bir özet görünür (ör. 📍 Konum: Merkez Ofis …).
Müşteriden gelen konum message.received olayında data.location alanıyla gelir.

Başlıklar

  • Idempotency-Keyisteğe bağlı
    Önerilir. 8–128 karakter. Aynı anahtar + aynı gövde ilk yanıtı döndürür (mesaj ikinci kez gitmez); aynı anahtar + farklı gövde 422 idempotency_key_conflict döner. 24 saat saklanır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Gönderimi yapacak numaranızın Meta kimliği. Numara size ait ve aktif olmalıdır.
  • tostringzorunlu
    Alıcının telefon numarası, uluslararası biçimde ve + olmadan (ör. 905550000000). Rakam dışı karakterler atılır; en az 10 hane gerekir. Telefonu olmayan alıcıda to yerine recipient gönderin.
  • recipientstringisteğe bağlı
    Telefonu görünmeyen kullanıcının WhatsApp kullanıcı kimliği (BSUID, webhook'taki user_id). Yalnız to boşken kullanılır. Eş anlamlıları: recipient_id, bsuid.
  • contextobjectisteğe bağlı
    Alıntılı yanıt. Alıcıda yanıtladığınız mesaj alıntı balonuyla görünür. Tepki mesajıyla birlikte kullanılamaz.
    Alt alanları göster
    • message_idstringzorunlu
      Yanıtlanan mesajın wamid değeri (webhook'taki data.wamid).
  • biz_opaque_callback_datastringisteğe bağlı
    En fazla 512 karakterlik kendi eşleştirme değeriniz. message.status.* olaylarında data.biz_opaque_callback_data olarak aynen döner. Göndermezseniz ve Idempotency-Key verdiyseniz sunucu bu alanı anahtarın değeriyle kendisi doldurur.
  • typestringzorunlu
    location.Değerler: location
  • locationobjectzorunlu
    Gönderilecek konum.
    Alt alanları göster
    • latitudenumber | stringzorunlu
      Enlem, −90 ile 90 arası. Sayı ya da sayısal metin.
    • longitudenumber | stringzorunlu
      Boylam, −180 ile 180 arası. Sayı ya da sayısal metin.
    • namestringisteğe bağlı
      Yer adı, en fazla 1000 karakter.
    • addressstringisteğe bağlı
      Açık adres, en fazla 1000 karakter.

Hatalar

DurumKodNe zaman
402insufficient_creditsMesaj krediniz yetersiz. Yanıtta error.balance döner.
403insufficient_scopeAnahtarda messages:send kapsamı yok.
404number_not_foundNumara size ait değil ya da aktif değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
409meta_outcome_unknownİstek Meta'ya iletildi ama sonucu doğrulanamadı. Aynı anahtarla tekrar göndermeyin; durum olayını bekleyin (retryable: false).
409idempotency_in_progressAynı Idempotency-Key ile bir istek hâlâ işleniyor.
422invalid_requestZorunlu alan eksik ya da biçim hatalı (error.field alanı belirtir).
422invalid_phoneAlıcı numarası geçersiz (en az 10 hane).
422idempotency_key_conflictAynı anahtar farklı bir gövdeyle kullanılmış.
422meta_send_failedMeta gönderimi reddetti. meta_code ve meta_subcode alanlarına bakın (retryable: true).
500send_failedSistem hatası; kredi iade edildi. Tekrar deneyebilirsiniz.
422invalid_locationEnlem/boylam eksik ya da aralık dışı, ad/adres çok uzun (error.field hatalı alanı gösterir).
422invalid_contextcontext.message_id geçerli bir wamid değil.
curl -X POST "https://api.verimerkezi.app/wa/messages" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "905550000000",
    "type": "location",
    "location": {
      "latitude": 41.0082,
      "longitude": 28.9784,
      "name": "Merkez Ofis",
      "address": "Örnek Mah. Örnek Cad. No:1, İstanbul"
    }
  }'
Yanıt 201
{
  "ok": true,
  "id": 48213,
  "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAERgSMUI4QzY3RDFFNzBBNDlGRTlBAA==",
  "to": "905550000000",
  "type": "location",
  "status": "sent",
  "mode": "live",
  "simulated": false,
  "credits_used": 1,
  "balance": 9875
}

#Kişi kartı gönder

POST/messages
Bir ya da birden çok kişi kartı (vCard) gönderir. Serbest mesajdır: yalnız 24 saatlik müşteri hizmet penceresi açıkken teslim edilir. Kapsam: messages:send
Canlı anahtarda her başarılı gönderim 1 kredi düşer. Kredi gönderimden önce ayrılır; gönderim başarısız olursa iade edilir.
Test anahtarıyla (vmk_test_) mesaj Meta'ya gönderilmez: simulated: true, credits_used: 0 ve test. ile başlayan sahte bir wamid döner.
Gönderim hatalarında hata nesnesi ayrıca retryable (bool), meta_code ve meta_subcode alanlarını taşır.
Meta'nın üst sınırı 257 karttır; okunabilirlik için tek mesajda en fazla 20 kart kabul edilir.
Müşteriden gelen kişi kartları message.received olayında data.contacts alanıyla gelir.

Başlıklar

  • Idempotency-Keyisteğe bağlı
    Önerilir. 8–128 karakter. Aynı anahtar + aynı gövde ilk yanıtı döndürür (mesaj ikinci kez gitmez); aynı anahtar + farklı gövde 422 idempotency_key_conflict döner. 24 saat saklanır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Gönderimi yapacak numaranızın Meta kimliği. Numara size ait ve aktif olmalıdır.
  • tostringzorunlu
    Alıcının telefon numarası, uluslararası biçimde ve + olmadan (ör. 905550000000). Rakam dışı karakterler atılır; en az 10 hane gerekir. Telefonu olmayan alıcıda to yerine recipient gönderin.
  • recipientstringisteğe bağlı
    Telefonu görünmeyen kullanıcının WhatsApp kullanıcı kimliği (BSUID, webhook'taki user_id). Yalnız to boşken kullanılır. Eş anlamlıları: recipient_id, bsuid.
  • contextobjectisteğe bağlı
    Alıntılı yanıt. Alıcıda yanıtladığınız mesaj alıntı balonuyla görünür. Tepki mesajıyla birlikte kullanılamaz.
    Alt alanları göster
    • message_idstringzorunlu
      Yanıtlanan mesajın wamid değeri (webhook'taki data.wamid).
  • biz_opaque_callback_datastringisteğe bağlı
    En fazla 512 karakterlik kendi eşleştirme değeriniz. message.status.* olaylarında data.biz_opaque_callback_data olarak aynen döner. Göndermezseniz ve Idempotency-Key verdiyseniz sunucu bu alanı anahtarın değeriyle kendisi doldurur.
  • typestringzorunlu
    contacts.Değerler: contacts
  • contactsarrayzorunlu
    1–20 kişi kartı (Meta biçimi). Bilinmeyen alanlar Meta'ya iletilmez.
    Alt alanları göster
    • nameobjectzorunlu
      formatted_name zorunlu; first_name, last_name, middle_name, prefix, suffix isteğe bağlı.
    • phonesarrayisteğe bağlı
      [{ phone, type, wa_id }]. wa_id verilirse alıcıda Mesaj gönder ve Kişiyi kaydet düğmeleri, verilmezse WhatsApp'a davet et görünür.
    • emailsarrayisteğe bağlı
      [{ email, type }].
    • urlsarrayisteğe bağlı
      [{ url, type }].
    • orgobjectisteğe bağlı
      { company, department, title }.
    • addressesarrayisteğe bağlı
      [{ street, city, state, zip, country, country_code, type }].
    • birthdaystringisteğe bağlı
      YYYY-MM-DD.

Hatalar

DurumKodNe zaman
402insufficient_creditsMesaj krediniz yetersiz. Yanıtta error.balance döner.
403insufficient_scopeAnahtarda messages:send kapsamı yok.
404number_not_foundNumara size ait değil ya da aktif değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
409meta_outcome_unknownİstek Meta'ya iletildi ama sonucu doğrulanamadı. Aynı anahtarla tekrar göndermeyin; durum olayını bekleyin (retryable: false).
409idempotency_in_progressAynı Idempotency-Key ile bir istek hâlâ işleniyor.
422invalid_requestZorunlu alan eksik ya da biçim hatalı (error.field alanı belirtir).
422invalid_phoneAlıcı numarası geçersiz (en az 10 hane).
422idempotency_key_conflictAynı anahtar farklı bir gövdeyle kullanılmış.
422meta_send_failedMeta gönderimi reddetti. meta_code ve meta_subcode alanlarına bakın (retryable: true).
500send_failedSistem hatası; kredi iade edildi. Tekrar deneyebilirsiniz.
422invalid_contactsKart sayısı 1–20 dışında ya da zorunlu alan eksik (ör. field: contacts[0].name.formatted_name).
422invalid_contextcontext.message_id geçerli bir wamid değil.
curl -X POST "https://api.verimerkezi.app/wa/messages" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "905550000000",
    "type": "contacts",
    "contacts": [
      {
        "name": {
          "formatted_name": "Destek Hattı",
          "first_name": "Destek",
          "last_name": "Hattı"
        },
        "phones": [
          {
            "phone": "+905550000000",
            "type": "WORK",
            "wa_id": "905550000000"
          }
        ],
        "emails": [
          {
            "email": "[email protected]",
            "type": "WORK"
          }
        ],
        "org": {
          "company": "Örnek A.Ş.",
          "title": "Müşteri Hizmetleri"
        },
        "urls": [
          {
            "url": "https://example.com",
            "type": "WORK"
          }
        ]
      }
    ]
  }'
Yanıt 201
{
  "ok": true,
  "id": 48213,
  "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAERgSMUI4QzY3RDFFNzBBNDlGRTlBAA==",
  "to": "905550000000",
  "type": "contacts",
  "status": "sent",
  "mode": "live",
  "simulated": false,
  "credits_used": 1,
  "balance": 9875
}

#Etkileşimli mesaj gönder

POST/messages
Yanıt düğmeleri, liste, bağlantı düğmesi ya da konum isteği gönderir. Gövde Meta Cloud API ile aynıdır; Meta sınırları gönderimden önce doğrulanır. Serbest mesajdır: yalnız 24 saatlik pencere açıkken teslim edilir. Kapsam: messages:send
Canlı anahtarda her başarılı gönderim 1 kredi düşer. Kredi gönderimden önce ayrılır; gönderim başarısız olursa iade edilir.
Test anahtarıyla (vmk_test_) mesaj Meta'ya gönderilmez: simulated: true, credits_used: 0 ve test. ile başlayan sahte bir wamid döner.
Gönderim hatalarında hata nesnesi ayrıca retryable (bool), meta_code ve meta_subcode alanlarını taşır.
Kolaylık: düğme { "id", "title" }, body ve footer düz metin olarak da verilebilir; Meta'ya her zaman resmî biçimde gider.
Müşterinin seçimi message.received (type: interactive) olayında data.interactive.reply_id, reply_title, reply_description ve geriye uyumlu data.button alanlarıyla gelir. Bağlantı düğmesine dokunmak olay üretmez.
Konum isteğine verilen yanıt message.received type: location olarak gelir; context.message_id isteğinizin wamid değeridir.

Başlıklar

  • Idempotency-Keyisteğe bağlı
    Önerilir. 8–128 karakter. Aynı anahtar + aynı gövde ilk yanıtı döndürür (mesaj ikinci kez gitmez); aynı anahtar + farklı gövde 422 idempotency_key_conflict döner. 24 saat saklanır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Gönderimi yapacak numaranızın Meta kimliği. Numara size ait ve aktif olmalıdır.
  • tostringzorunlu
    Alıcının telefon numarası, uluslararası biçimde ve + olmadan (ör. 905550000000). Rakam dışı karakterler atılır; en az 10 hane gerekir. Telefonu olmayan alıcıda to yerine recipient gönderin.
  • recipientstringisteğe bağlı
    Telefonu görünmeyen kullanıcının WhatsApp kullanıcı kimliği (BSUID, webhook'taki user_id). Yalnız to boşken kullanılır. Eş anlamlıları: recipient_id, bsuid.
  • contextobjectisteğe bağlı
    Alıntılı yanıt. Alıcıda yanıtladığınız mesaj alıntı balonuyla görünür. Tepki mesajıyla birlikte kullanılamaz.
    Alt alanları göster
    • message_idstringzorunlu
      Yanıtlanan mesajın wamid değeri (webhook'taki data.wamid).
  • biz_opaque_callback_datastringisteğe bağlı
    En fazla 512 karakterlik kendi eşleştirme değeriniz. message.status.* olaylarında data.biz_opaque_callback_data olarak aynen döner. Göndermezseniz ve Idempotency-Key verdiyseniz sunucu bu alanı anahtarın değeriyle kendisi doldurur.
  • typestringzorunlu
    interactive.Değerler: interactive
  • interactiveobjectzorunlu
    Meta interactive nesnesi.
    Alt alanları göster
    • typestringzorunlu
      button (1–3 yanıt düğmesi), list (en çok 10 satır), cta_url (bağlantı düğmesi), location_request_message (konum isteği).Değerler: button, list, cta_url, location_request_message
    • headerobjectisteğe bağlı
      text (≤ 60) ya da düğmeli/bağlantılı mesajda image, video, document (link ya da POST /media kimliği). Listede yalnız metin; konum isteğinde kullanılamaz.
    • bodyobjectzorunlu
      { "text": "..." } — düğme, bağlantı ve konum isteğinde ≤ 1024, listede ≤ 4096 karakter.
    • footerobjectisteğe bağlı
      { "text": "..." }, ≤ 60 karakter. Konum isteğinde kullanılamaz.
    • actionobjectzorunlu
      Düğme: buttons[] (reply.id ≤ 256, reply.title ≤ 20, benzersiz). Liste: button (≤ 20) + sections[] (1–10 bölüm, toplam 1–10 satır; satır id ≤ 200, title ≤ 24, description ≤ 72). Bağlantı: name: cta_url, parameters.display_text (≤ 20), parameters.url (http/https, ≤ 2000). Konum isteği: name: send_location (verilmezse eklenir).

Hatalar

DurumKodNe zaman
402insufficient_creditsMesaj krediniz yetersiz. Yanıtta error.balance döner.
403insufficient_scopeAnahtarda messages:send kapsamı yok.
404number_not_foundNumara size ait değil ya da aktif değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
409meta_outcome_unknownİstek Meta'ya iletildi ama sonucu doğrulanamadı. Aynı anahtarla tekrar göndermeyin; durum olayını bekleyin (retryable: false).
409idempotency_in_progressAynı Idempotency-Key ile bir istek hâlâ işleniyor.
422invalid_requestZorunlu alan eksik ya da biçim hatalı (error.field alanı belirtir).
422invalid_phoneAlıcı numarası geçersiz (en az 10 hane).
422idempotency_key_conflictAynı anahtar farklı bir gövdeyle kullanılmış.
422meta_send_failedMeta gönderimi reddetti. meta_code ve meta_subcode alanlarına bakın (retryable: true).
500send_failedSistem hatası; kredi iade edildi. Tekrar deneyebilirsiniz.
422invalid_interactiveinteractive nesnesi hatalı ya da Meta sınırını aşıyor (error.field hatalı alanı gösterir, ör. interactive.action.buttons[1].reply.title).
422invalid_contextcontext.message_id geçerli bir wamid değil.
curl -X POST "https://api.verimerkezi.app/wa/messages" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "905550000000",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "header": {
        "type": "text",
        "text": "Randevu"
      },
      "body": {
        "text": "Yarın 14:00 randevunuzu onaylıyor musunuz?"
      },
      "footer": {
        "text": "Örnek Klinik"
      },
      "action": {
        "buttons": [
          {
            "type": "reply",
            "reply": {
              "id": "onay",
              "title": "Onaylıyorum"
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "degistir",
              "title": "Saati değiştir"
            }
          }
        ]
      }
    }
  }'
Yanıt 201
{
  "ok": true,
  "id": 48213,
  "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAERgSMUI4QzY3RDFFNzBBNDlGRTlBAA==",
  "to": "905550000000",
  "type": "interactive",
  "status": "sent",
  "mode": "live",
  "simulated": false,
  "credits_used": 1,
  "balance": 9875
}

#Tepki gönder

POST/messages
Bir mesaja emoji tepkisi verir ya da mevcut tepkiyi kaldırır. Kapsam: messages:send
Canlı anahtarda her başarılı gönderim 1 kredi düşer. Kredi gönderimden önce ayrılır; gönderim başarısız olursa iade edilir.
Test anahtarıyla (vmk_test_) mesaj Meta'ya gönderilmez: simulated: true, credits_used: 0 ve test. ile başlayan sahte bir wamid döner.
Gönderim hatalarında hata nesnesi ayrıca retryable (bool), meta_code ve meta_subcode alanlarını taşır.
Tepki mesajı context ile birlikte gönderilemez (422 invalid_request).

Başlıklar

  • Idempotency-Keyisteğe bağlı
    Önerilir. 8–128 karakter. Aynı anahtar + aynı gövde ilk yanıtı döndürür (mesaj ikinci kez gitmez); aynı anahtar + farklı gövde 422 idempotency_key_conflict döner. 24 saat saklanır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Gönderimi yapacak numaranızın Meta kimliği. Numara size ait ve aktif olmalıdır.
  • tostringzorunlu
    Alıcının telefon numarası, uluslararası biçimde ve + olmadan (ör. 905550000000). Rakam dışı karakterler atılır; en az 10 hane gerekir. Telefonu olmayan alıcıda to yerine recipient gönderin.
  • recipientstringisteğe bağlı
    Telefonu görünmeyen kullanıcının WhatsApp kullanıcı kimliği (BSUID, webhook'taki user_id). Yalnız to boşken kullanılır. Eş anlamlıları: recipient_id, bsuid.
  • biz_opaque_callback_datastringisteğe bağlı
    En fazla 512 karakterlik kendi eşleştirme değeriniz. message.status.* olaylarında data.biz_opaque_callback_data olarak aynen döner. Göndermezseniz ve Idempotency-Key verdiyseniz sunucu bu alanı anahtarın değeriyle kendisi doldurur.
  • typestringzorunlu
    reaction olmalıdır.Değerler: reaction
  • reactionobjectzorunlu
    Tepki.
    Alt alanları göster
    • message_idstringzorunlu
      Tepki verilen mesajın wamid değeri.
    • emojistringzorunlu
      Tek emoji. Boş metin ("") önceki tepkiyi kaldırır.

Hatalar

DurumKodNe zaman
402insufficient_creditsMesaj krediniz yetersiz. Yanıtta error.balance döner.
403insufficient_scopeAnahtarda messages:send kapsamı yok.
404number_not_foundNumara size ait değil ya da aktif değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
409meta_outcome_unknownİstek Meta'ya iletildi ama sonucu doğrulanamadı. Aynı anahtarla tekrar göndermeyin; durum olayını bekleyin (retryable: false).
409idempotency_in_progressAynı Idempotency-Key ile bir istek hâlâ işleniyor.
422invalid_requestZorunlu alan eksik ya da biçim hatalı (error.field alanı belirtir).
422invalid_phoneAlıcı numarası geçersiz (en az 10 hane).
422idempotency_key_conflictAynı anahtar farklı bir gövdeyle kullanılmış.
422meta_send_failedMeta gönderimi reddetti. meta_code ve meta_subcode alanlarına bakın (retryable: true).
500send_failedSistem hatası; kredi iade edildi. Tekrar deneyebilirsiniz.
422invalid_reactionreaction.message_id geçerli bir wamid değil ya da emoji tek emoji değil.
curl -X POST "https://api.verimerkezi.app/wa/messages" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "905550000000",
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAEhggQTNFQkQ2RjQ3MEIyQzk0RTE4AA==",
      "emoji": "👍"
    }
  }'
Yanıt 201
{
  "ok": true,
  "id": 48213,
  "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAERgSMUI4QzY3RDFFNzBBNDlGRTlBAA==",
  "to": "905550000000",
  "type": "reaction",
  "status": "sent",
  "mode": "live",
  "simulated": false,
  "credits_used": 1,
  "balance": 9875
}

#Form mesajı gönder

POST/messages
Müşteriye WhatsApp içinde açılan bir form (WhatsApp Flow) gönderir. Form yanıtı flow.completed olayıyla gelir. Serbest mesaj kuralları geçerlidir: 24 saat penceresi ve 1 kredi. Kapsam: messages:send
Canlı anahtarda her başarılı gönderim 1 kredi düşer. Kredi gönderimden önce ayrılır; gönderim başarısız olursa iade edilir.
Test anahtarıyla (vmk_test_) mesaj Meta'ya gönderilmez: simulated: true, credits_used: 0 ve test. ile başlayan sahte bir wamid döner.
Gönderim hatalarında hata nesnesi ayrıca retryable (bool), meta_code ve meta_subcode alanlarını taşır.
Pencere kapalıyken form butonlu bir şablon kullanın (bkz. Şablon mesajı gönder).

Başlıklar

  • Idempotency-Keyisteğe bağlı
    Önerilir. 8–128 karakter. Aynı anahtar + aynı gövde ilk yanıtı döndürür (mesaj ikinci kez gitmez); aynı anahtar + farklı gövde 422 idempotency_key_conflict döner. 24 saat saklanır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Gönderimi yapacak numaranızın Meta kimliği. Numara size ait ve aktif olmalıdır.
  • tostringzorunlu
    Alıcının telefon numarası, uluslararası biçimde ve + olmadan (ör. 905550000000). Rakam dışı karakterler atılır; en az 10 hane gerekir. Telefonu olmayan alıcıda to yerine recipient gönderin.
  • recipientstringisteğe bağlı
    Telefonu görünmeyen kullanıcının WhatsApp kullanıcı kimliği (BSUID, webhook'taki user_id). Yalnız to boşken kullanılır. Eş anlamlıları: recipient_id, bsuid.
  • contextobjectisteğe bağlı
    Alıntılı yanıt. Alıcıda yanıtladığınız mesaj alıntı balonuyla görünür. Tepki mesajıyla birlikte kullanılamaz.
    Alt alanları göster
    • message_idstringzorunlu
      Yanıtlanan mesajın wamid değeri (webhook'taki data.wamid).
  • biz_opaque_callback_datastringisteğe bağlı
    En fazla 512 karakterlik kendi eşleştirme değeriniz. message.status.* olaylarında data.biz_opaque_callback_data olarak aynen döner. Göndermezseniz ve Idempotency-Key verdiyseniz sunucu bu alanı anahtarın değeriyle kendisi doldurur.
  • typestringzorunlu
    flow olmalıdır.Değerler: flow
  • flowobjectzorunlu
    WhatsApp Flow (form) mesajı.
    Alt alanları göster
    • flow_idstringisteğe bağlı
      Form kimliği. flow_id ya da flow_name alanlarından yalnız biri verilir.
    • flow_namestringisteğe bağlı
      Form adı (flow_id yerine).
    • flow_tokenstringisteğe bağlı
      Kendi eşleştirme anahtarınız (en fazla 191 bayt). Verilmezse vmf_ önekli bir değer üretilir ve yanıtta döner; flow.completed olayında aynen gelir.
    • ctastringzorunlu
      Buton metni; en fazla 20 karakter, emoji yok.
    • bodystringzorunlu
      Gövde metni; en fazla 1024 karakter.
    • headerstringisteğe bağlı
      Başlık; en fazla 60 karakter.
    • footerstringisteğe bağlı
      Alt bilgi; en fazla 60 karakter.
    • modestringisteğe bağlı
      draft, yayınlanmamış formu denemek içindir.Değerler: published, draftVarsayılan: published
    • actionstringisteğe bağlı
      data_exchange yalnız Endpoint'li formlar içindir.Değerler: navigate, data_exchangeVarsayılan: navigate
    • screenstringisteğe bağlı
      Açılış ekranı; navigate eyleminde zorunludur.
    • dataobjectisteğe bağlı
      Açılış ekranına verilecek başlangıç verisi (navigate).

Hatalar

DurumKodNe zaman
402insufficient_creditsMesaj krediniz yetersiz. Yanıtta error.balance döner.
403insufficient_scopeAnahtarda messages:send kapsamı yok.
404number_not_foundNumara size ait değil ya da aktif değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
409meta_outcome_unknownİstek Meta'ya iletildi ama sonucu doğrulanamadı. Aynı anahtarla tekrar göndermeyin; durum olayını bekleyin (retryable: false).
409idempotency_in_progressAynı Idempotency-Key ile bir istek hâlâ işleniyor.
422invalid_requestZorunlu alan eksik ya da biçim hatalı (error.field alanı belirtir).
422invalid_phoneAlıcı numarası geçersiz (en az 10 hane).
422idempotency_key_conflictAynı anahtar farklı bir gövdeyle kullanılmış.
422meta_send_failedMeta gönderimi reddetti. meta_code ve meta_subcode alanlarına bakın (retryable: true).
500send_failedSistem hatası; kredi iade edildi. Tekrar deneyebilirsiniz.
422invalid_flowflow nesnesi hatalı (error.field alanı belirtir).
curl -X POST "https://api.verimerkezi.app/wa/messages" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "to": "905550000000",
    "type": "flow",
    "flow": {
      "flow_id": "1234567890123456",
      "flow_token": "crm-basvuru-42",
      "cta": "Formu Aç",
      "body": "Başvurunuzu 1 dakikada tamamlayın.",
      "screen": "WELCOME",
      "data": {
        "ad": "Ahmet"
      }
    }
  }'
Yanıt 201
{
  "ok": true,
  "id": 48213,
  "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAERgSMUI4QzY3RDFFNzBBNDlGRTlBAA==",
  "to": "905550000000",
  "type": "flow",
  "status": "sent",
  "mode": "live",
  "simulated": false,
  "credits_used": 1,
  "balance": 9875,
  "flow": {
    "flow_token": "crm-basvuru-42",
    "flow_id": "1234567890123456",
    "flow_name": null,
    "mode": "published"
  }
}

#Okundu işaretle ve yazıyor göster

POST/messages/read
Gelen bir mesajı okundu olarak işaretler (mavi tik). typing: true ile alıcıda yaklaşık 25 saniye "yazıyor…" göstergesi çıkar. Kredi düşmez. Kapsam: messages:send
Bu uç gönderim sayacını değil, kendi hız sayacını kullanır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Mesajın geldiği numaranızın Meta kimliği.
  • message_idstringzorunlu
    Okundu işaretlenecek gelen mesajın wamid değeri.
  • typingbooleanisteğe bağlı
    "Yazıyor…" göstergesi.Varsayılan: False

Hatalar

DurumKodNe zaman
403insufficient_scopeAnahtarda messages:send kapsamı yok.
404number_not_foundNumara size ait değil ya da aktif değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
422invalid_requestphone_number_id ya da message_id eksik.
422meta_errorMeta isteği reddetti (meta_code).
curl -X POST "https://api.verimerkezi.app/wa/messages/read" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "message_id": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAEhggQTNFQkQ2RjQ3MEIyQzk0RTE4AA==",
    "typing": true
  }'
Yanıt 200
{
  "ok": true,
  "marked_read": true,
  "typing": true
}

#Mesaj kayıtlarını listele

GET/messages
Bir numaranın gelen ve giden mesaj kayıtlarını zamana göre artan sırada döndürür. Webhook teslimi kaçtığında olayları geri almak (uzlaştırma) için kullanın. Kredi düşmez. Kapsam: messages:read ya da inbox:read
messages:read ya da inbox:read kapsamlarından biri yeterlidir.
Gelen ve coexistence kayıtlarında context, reaction, location, contacts, original_message_id, button alanları da döner.

Sorgu parametreleri

  • phone_number_idstringzorunlu
    Numaranızın Meta kimliği.
  • sincestringisteğe bağlı
    ISO 8601 başlangıç zamanı. En fazla 90 gün geriye gider; verilmezse son 24 saat.
  • cursorintegeristeğe bağlı
    Önceki yanıttaki next_cursor. Bu kimlikten büyük kayıtlar döner.Varsayılan: 0
  • limitintegeristeğe bağlı
    Sayfa boyutu (1–100).Varsayılan: 50

Hatalar

DurumKodNe zaman
403insufficient_scopeAnahtarda messages:read ya da inbox:read kapsamı yok.
404number_not_foundNumara size ait değil.
422invalid_requestphone_number_id eksik ya da rakam değil.
422invalid_sincesince ISO 8601 değil.
curl -X GET "https://api.verimerkezi.app/wa/messages?phone_number_id=1234567890&since=2026-10-09T00%3A00%3A00Z&limit=100" \
  -H "Authorization: Bearer $VM_API_KEY"
Yanıt 200
{
  "ok": true,
  "phone_number_id": "1234567890",
  "data": [
    {
      "id": 248117,
      "wamid": "wamid.HBgMOTA1NTUxMjM0NTY3FQIAEhggQTNFQkQ2RjQ3MEIyQzk0RTE4AA==",
      "direction": "inbound",
      "type": "text",
      "status": "received",
      "from": "905550000000",
      "to": null,
      "user_id": null,
      "username": null,
      "text": "Merhaba, siparişim ne durumda?",
      "media": null,
      "template_name": null,
      "campaign_id": null,
      "is_test": false,
      "error": null,
      "created_at": "2026-10-10T10:00:00+03:00",
      "sent_at": null,
      "delivered_at": null,
      "read_at": null,
      "failed_at": null,
      "context": null,
      "reaction": null,
      "location": null,
      "contacts": null,
      "original_message_id": null,
      "button": null
    }
  ],
  "has_more": true,
  "next_cursor": 248117
}

#Test gelen mesajı oluştur

POST/test/inbound
Yalnız test anahtarıyla çalışır. Sahte bir gelen mesajı gerçek gelen mesaj hattından geçirir ve imzalı message.received, message.revoked ya da message.edited olayını (app_contact_sync ile contact.synced olayını) aktif webhook aboneliklerinize gönderir. Meta'ya istek gitmez.
injected nesnesinin içeriği örnektir.
Ek kapsam gerekmez; yalnız test anahtarı şarttır.

İstek gövdesi

  • phone_number_idstringzorunlu
    Numaranızın Meta kimliği.
  • typestringisteğe bağlı
    Sahte olay türü. app_contact_sync örnek bir contact.synced olayı gönderir (add, update, remove; rehbere kayıt yazılmaz).Değerler: text, revoke, edit, app_contact_syncVarsayılan: text
  • fromstringisteğe bağlı
    Gönderen telefon (8–15 hane).Varsayılan: 905550000000
  • textstringisteğe bağlı
    Mesaj metni (en fazla 4096). text ve edit için zorunlu.
  • original_message_idstringisteğe bağlı
    revoke ve edit için hedef mesajın wamid değeri.

Hatalar

DurumKodNe zaman
403test_onlyBu uç yalnız vmk_test_ anahtarıyla kullanılır.
404number_not_foundNumara size ait değil.
409number_detachedNumara hesabınızdan ayrılmış; panelden yeniden bağlayın.
422invalid_requestParametre hatalı.
500test_inbound_failedSahte mesaj işlenemedi.
curl -X POST "https://api.verimerkezi.app/wa/test/inbound" \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "1234567890",
    "type": "text",
    "from": "905550000000",
    "text": "Merhaba, bu bir test mesajıdır."
  }'
Yanıt 202
{
  "ok": true,
  "mode": "test",
  "simulated": true,
  "phone_number_id": "1234567890",
  "injected": {
    "wamid": "test.in.8f2c1a9b"
  },
  "note": "İmzalı olay(lar) hesabın aktif webhook aboneliklerine gönderildi. Meta'ya istek gitmedi."
}