API referansı
CTWA Dönüşümleri
Click-to-WhatsApp (CTWA) reklamlarından gelen satış/dönüşümleri Meta'ya bildirir (Conversions API for Business Messaging). Müşteri bir reklama/gönderiye tıklayıp sohbeti başlattığında Meta, ilk gelen mesajın referral nesnesinde ctwa_clid gönderir; bunu kişi bazında saklarız. Satış gerçekleştiğinde POST /conversions ile Purchase (ya da başka) olayı iletilir; ctwa_clid vermezseniz ilgili müşteri (to) için yakalanmış son tıklama kullanılır. İletim için numaranın Meta erişim anahtarında whatsapp_business_manage_events izni gerekir; yoksa 403 manage_events_permission_required döner. Olaylar event_id ile tekilleştirilir (Meta tekilleştirmez).
#Conversion nesnesi
event_idstringTekilleştirme kimliği. Verilmezseorder_id, o da yoksa türetilir.event_namestringDönüşüm olayı adı (ör.Purchase).ctwa_clidstringİlişkilendirilen reklam tıklaması kimliği (yankıda kısmen maskelenir).valuenumber · boş olabilirSatış tutarı.currencystring · boş olabilirISO 4217 para birimi (ör.TRY).dataset_idstring · boş olabilirOlayın gönderildiği Meta dataset kimliği (WABA başına, otomatik oluşturulur/önbelleğe alınır).statusstringİletim durumu.Değerler:sent,failed,permissionevents_receivedinteger · boş olabilirMeta'nın kabul ettiği olay sayısı.
Conversion nesnesi
{
"ok": true,
"event_id": "VM261113155546D6",
"event_name": "Purchase",
"dataset_id": "1298340012345678",
"events_received": 1,
"duplicate": false,
"ctwa_clid": "ARAb1C…k9Qd"
}#Dönüşüm (satış) bildir
POST
/conversionsClick-to-WhatsApp reklamından gelen bir satış/dönüşüm olayını Meta'ya iletir.
ctwa_clid doğrudan gönderilebilir; gönderilmezse to (müşteri numarası) için yakalanmış son reklam tıklaması kullanılır. Değer bildirecekseniz value ile birlikte currency zorunludur. Aynı event_id yeniden gönderilirse olay tekrar iletilmez (duplicate: true). Kapsam: conversions:writeDataset WABA başına otomatik oluşturulur ve
wa_clients'ta önbelleğe alınır; ayrı kurulum gerekmez.Test anahtarıyla (
vmk_test_) çağrı Meta'ya gitmez; simulated: true ve sahte dataset_id döner.ctwa_clid yankıda güvenlik için kısmen maskelenir; tam değeri GET /conversions/click ile alırsınız.İstek gövdesi
phone_number_idstringzorunluDönüşümün ilişkili olduğu numaranınphone_number_iddeğeri (yalnız rakam).event_namestringisteğe bağlıDönüşüm olayı adı. VarsayılanPurchase.Değerler:Purchase,Lead,LeadSubmitted,InitiateCheckout,AddToCart,ViewContent,Subscribe,CompleteRegistration,Contact,Schedule,StartTrialVarsayılan:Purchasetostringisteğe bağlıMüşteri WhatsApp numarası.ctwa_clidverilmediğinde bu numara için yakalanmış son reklam tıklaması kullanılır.ctwa_clidstringisteğe bağlıİlişkilendirilecek reklam tıklaması kimliği. Verilirsetoaraması yapılmaz.valuenumberisteğe bağlıSatış tutarı. Gönderilirsecurrencyzorunludur.currencystringisteğe bağlıISO 4217 para birimi (3 harf), ör.TRY.event_timeintegeristeğe bağlıOlayın gerçekleştiği Unix zaman damgası (saniye). Varsayılan şimdiki zaman.event_idstringisteğe bağlıTekilleştirme kimliği. Verilmezseorder_id, o da yoksactwa_clid+ olaydan türetilir.order_idstringisteğe bağlıSipariş kimliği.event_idverilmezse tekilleştirme için kullanılır.custom_dataobjectisteğe bağlıMeta olayına eklenecek ek alanlar (value/currencyburaya da yazılır).
Hatalar
| Durum | Kod | Ne zaman |
|---|---|---|
| 403 | insufficient_scope | Anahtarda conversions:write kapsamı yok. |
| 403 | manage_events_permission_required | Numaranın Meta erişim anahtarında whatsapp_business_manage_events izni yok; Meta dataset'e yazmayı reddetti. |
| 404 | number_not_found | phone_number_id hesabınızda aktif değil. |
| 422 | invalid_event_name | Desteklenmeyen event_name (geçerli değerler listesi mesajda döner). |
| 422 | ctwa_clid_required | ctwa_clid verilmedi ve to için yakalanmış reklam tıklaması yok. |
| 422 | currency_required | value gönderildi ama currency yok. |
| 502 | conversion_failed | Meta olayı kabul etmedi (ayrıntı message alanında). |
curl -X POST "https://api.verimerkezi.app/wa/conversions" \
-H "Authorization: Bearer $VM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number_id": "1234567890",
"event_name": "Purchase",
"value": 1990,
"currency": "TRY",
"to": "905550000000",
"order_id": "VM261113155546D6"
}'const res = await fetch("https://api.verimerkezi.app/wa/conversions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.VM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"phone_number_id": "1234567890",
"event_name": "Purchase",
"value": 1990,
"currency": "TRY",
"to": "905550000000",
"order_id": "VM261113155546D6"
}),
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.verimerkezi.app/wa/conversions",
headers={"Authorization": f"Bearer {os.environ['VM_API_KEY']}"},
json={
"phone_number_id": "1234567890",
"event_name": "Purchase",
"value": 1990,
"currency": "TRY",
"to": "905550000000",
"order_id": "VM261113155546D6"
},
)
data = res.json()<?php
$ch = curl_init("https://api.verimerkezi.app/wa/conversions");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("VM_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"phone_number_id" => "1234567890",
"event_name" => "Purchase",
"value" => 1990,
"currency" => "TRY",
"to" => "905550000000",
"order_id" => "VM261113155546D6"
]),
]);
$data = json_decode(curl_exec($ch), true);Yanıt 200
{
"ok": true,
"event_id": "VM261113155546D6",
"event_name": "Purchase",
"dataset_id": "1298340012345678",
"events_received": 1,
"duplicate": false,
"ctwa_clid": "ARAb1C…k9Qd"
}#İletilen dönüşümleri listele
GET
/conversionsHesabınız için en son iletilen dönüşüm olaylarını durum ve hata bilgisiyle döndürür. Kapsam:
conversions:readSorgu parametreleri
limitintegeristeğe bağlıDönecek kayıt sayısı (1–100).Varsayılan:25
Hatalar
| Durum | Kod | Ne zaman |
|---|---|---|
| 403 | insufficient_scope | Anahtarda conversions:read kapsamı yok. |
curl -X GET "https://api.verimerkezi.app/wa/conversions?limit=25" \
-H "Authorization: Bearer $VM_API_KEY"const res = await fetch("https://api.verimerkezi.app/wa/conversions?limit=25", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.VM_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://api.verimerkezi.app/wa/conversions?limit=25",
headers={"Authorization": f"Bearer {os.environ['VM_API_KEY']}"},
)
data = res.json()<?php
$ch = curl_init("https://api.verimerkezi.app/wa/conversions?limit=25");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("VM_API_KEY"),
],
]);
$data = json_decode(curl_exec($ch), true);Yanıt 200
{
"ok": true,
"conversions": [
{
"event_id": "VM261113155546D6",
"event_name": "Purchase",
"phone_number_id": "1234567890",
"ctwa_clid": "ARAb1C…k9Qd",
"value": 1990,
"currency": "TRY",
"dataset_id": "1298340012345678",
"status": "sent",
"error": null,
"created_at": "2026-11-13 15:55:46"
}
]
}#Kişi için yakalanmış tıklamayı getir
GET
/conversions/clickBir müşteri için yakalanmış en güncel CTWA reklam tıklamasını (
ctwa_clid ve reklam bilgisi) döndürür. Dönüşümü kendi sisteminizden Meta'ya iletecekseniz tam ctwa_clid'i buradan alırsınız. Kapsam: conversions:readİlişkilendirme penceresi varsayılan 7 gündür; daha eski tıklamalar
found: false döner.Sorgu parametreleri
phone_number_idstringzorunluNumaranınphone_number_iddeğeri.tostringzorunluMüşteri WhatsApp numarası.
Hatalar
| Durum | Kod | Ne zaman |
|---|---|---|
| 403 | insufficient_scope | Anahtarda conversions:read kapsamı yok. |
| 404 | number_not_found | phone_number_id hesabınızda yok. |
| 422 | invalid_request | phone_number_id ve to zorunludur. |
curl -X GET "https://api.verimerkezi.app/wa/conversions/click?phone_number_id=1234567890&to=905551234567" \
-H "Authorization: Bearer $VM_API_KEY"const res = await fetch("https://api.verimerkezi.app/wa/conversions/click?phone_number_id=1234567890&to=905551234567", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.VM_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://api.verimerkezi.app/wa/conversions/click?phone_number_id=1234567890&to=905551234567",
headers={"Authorization": f"Bearer {os.environ['VM_API_KEY']}"},
)
data = res.json()<?php
$ch = curl_init("https://api.verimerkezi.app/wa/conversions/click?phone_number_id=1234567890&to=905551234567");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("VM_API_KEY"),
],
]);
$data = json_decode(curl_exec($ch), true);Yanıt 200
{
"ok": true,
"found": true,
"ctwa_clid": "ARAb1CdEf…xyz0k9Qd",
"source_id": "120210000000000000",
"source_type": "ad",
"headline": "Hemen keşfet",
"received_at": "2026-11-13 14:02:10"
}