TL;DR: Whapi.Cloud, ctwa_clid'yi her Click-to-WhatsApp webhook'una context.ad.ctwa altında, sizden hiçbir yapılandırma gerektirmeden ekler. Değeri okuyun, CRM'inizde saklayın, ardından WhatsApp reklam harcamalarınızı atfedilebilir kılmak için Meta Dönüşüm API'sine user_data.ctwa_clid olarak POST gönderin. context.ad yoksa mesaj organiktir: o etkinlik için CAPI raporlamasını atlayın. Varsayılan olay adı olarak Lead kullanın.
Click-to-WhatsApp Reklamcılığı Nedir?
Click-to-WhatsApp (CTWA) reklamları, Facebook ve Instagram'daki Meta reklam formatlarıdır. Harekete geçirici mesaja dokunmak, ara bir açılış sayfası veya form olmadan doğrudan bir WhatsApp konuşması açar.
Kullanıcı reklama dokunur, WhatsApp açılır ve ilk mesajı doğrudan gelen kutunuza düşer. WhatsApp'ın içinde standart bir tarayıcı pikseli kullanıcıyı takip edemez. ctwa_clid ortaya çıkmadan önce, tüm WhatsApp reklam harcamaları fiilen atfedilemezdi: reklamınıza tıklayan bir lead, numaranızı manuel olarak yazan birinden ayırt edilemiyordu.
ctwa_clid Nedir ve Nasıl Çalışır?
Bir kullanıcı Click-to-WhatsApp reklamına dokunduğunda Meta, konuşmaya ctwa_clid adlı bir tıklama tanımlayıcısı enjekte eder.
Tanımlayıcı ilk gelen mesajla birlikte iletilir ve WhatsApp lead'ini onu oluşturan tam reklam, kampanya ve kitle segmentiyle ilişkilendirmenizi sağlar.
Bir UTM tıklama kimliğinin aksine, ctwa_clid bir URL sorgu dizesinde değil, mesaj meta verilerinde yaşar. Meta bunu reklam dokunuşu anında oluşturur ve ilk gelen mesajın referral nesnesine ekler.
Whapi.Cloud, ctwa_clid'yi uygun her gelen webhook'ta context.ad.ctwa üzerinden doğal olarak sunar. Sizden sıfır yapılandırma: özel bayrak yok, ek API çağrısı yok. Bazı sağlayıcılar payload'unuz işleyicinize ulaşmadan referral nesnesini kaldırır veya atlar. Whapi.Cloud tam atıf nesnesini varsayılan olarak iletir.
Aynı webhook etkinliğinde birlikte gelen üç atıf alanı:
-
context.ad.ctwa:
ctwa_cliddeğerinin kendisi. Çevrimdışı dönüşümü raporlamak için Meta Dönüşüm API'sineuser_data.ctwa_clidolarak gönderdiğiniz tanımlayıcıdır. -
context.conversion.data: tekilleştirme token'ı. Bunu CAPI payload'unuzda
event_idolarak geçirin. Yapılandırmanız aynı oturum için bir tarayıcı pikselini de tetikliyorsa Meta bu token'ı kullanarak sunucu tarafı ve istemci tarafı etkinlikleri tekilleştirir; böylece dönüşüm iki kez değil bir kez sayılır. -
context.ad.source.id, belirli reklam kreatifini tanımlar. Kreatif düzeyinde atıfa ihtiyacınız olduğunda bunu
ctwa_clidile eşleştirin: yalnızca "bu lead X kampanyasından geldi" değil, "bu lead o belirli başlık ve görsel içeren carousel varyantından geldi".
Ön Koşullar: ctwa_clid Görmeden Önce Kontrol Edilmesi Gereken Üç Şey
ctwa_clid'nin webhook'larınızda görünmesi için üç koşulun da sağlanması gerekir. Herhangi biri eksikse webhook işleyiciniz nasıl yazılmış olursa olsun context.ad mevcut olmayacaktır.
- Aktif bir Click-to-WhatsApp kampanyası. Gelen mesaj bir CTWA reklam dokunuşundan kaynaklanmalıdır. Organik kişiler (numaranızı arama, paylaşılan bağlantı veya doğrudan giriş yoluyla bulan kullanıcılar) ekli referral verisi olmayan mesajlar gönderir.
- WhatsApp Business ayarlarında atıf etkinleştirilmiş. Bu, çoğu ekibin kaçırdığı adımdır. WhatsApp Business hesabı ayarlarınızı açın, Reklam Atıfı bölümünü bulun ve etkinleştirin. Bu geçiş olmadan Meta, konuşmaya referral nesnesini eklemez ve
context.adhiçbir webhook payload'unda görünmez. - Yapılandırılmış bir Whapi.Cloud webhook endpoint'i. Backend URL'niz Whapi.Cloud panosuna kayıtlı olmalı ve kamuya açık olarak erişilebilir olmalıdır. Standart webhook kurulumu geçerlidir: Whapi.Cloud tarafında özel atıf modu veya ek izin gerekmez.
Whapi.Cloud Webhook'u: ctwa_clid Nerede Bulunur?
CTWA atıflı bir mesaj geldiğinde Whapi.Cloud, standart mesaj alanlarının yanı sıra context nesnesi içeren bir webhook payload'u teslim eder. Bu nesnenin iki alt anahtarı vardır: ad (tıklama kaynağı verileri) ve conversion (tekilleştirme token'ı).
Aşağıda atıflı bir Click-to-WhatsApp mesajı için tam Whapi.Cloud webhook payload'u yer almaktadır. context bloğunu inceleyin: CAPI raporlaması için ihtiyaç duyulan her şey oradadır.
{
"messages": [
{
"id": "msg_id_123",
"from_me": false,
"type": "text",
"chat_id": "[email protected]",
"timestamp": 1714000000,
"source": "mobile",
"text": {
"body": "Hi, I saw your ad and I'm interested"
},
"context": {
"conversion": {
"data": "CONVERSION_TOKEN_ABC123",
"source": "FB_Ads"
},
"ad": {
"title": "Summer Sale — 50% Off",
"body": "Limited time offer. Click to chat now.",
"media_type": "image",
"preview_url": "https://example.com/ad-preview.jpg",
"source": {
"id": "AD_ID_987654321",
"type": "ad",
"url": "https://fb.me/adlink123"
},
"attrib": true,
"ctwa": "CTWA_CLICK_ID_1234567890"
}
},
"from": "60123456789",
"from_name": "John Doe"
}
]
}Ezberlenecek iki yol: messages[0].context.ad.ctwa ctwa_clid'dir. messages[0].context.conversion.data ise tekilleştirme token'ıdır. Eksiksiz bir CAPI payload'u için her ikisi de gereklidir.
context.ad.source.id de aynı webhook'ta iletilir: bu reklam kreatif kimliğidir. Tek bir webhook etkinliği, kullanıcı düzeyinde atıfı (ctwa_clid) ve kreatif düzeyinde atıfı (reklam kimliği) eş zamanlı olarak sunar. Kullanıcının hangi kreatifi gördüğünü öğrenmek için ikinci bir API çağrısına gerek yoktur.
Tam alan referansı ve uç durum örnekleri için Whapi.Cloud bilgi bankasının Meta reklamlarından WhatsApp lead'lerini takip etme makalesine bakın. Tüm context alanları dahil tam gelen webhook payload spesifikasyonu gelen webhook formatı referansında yer almaktadır.
Adım Adım: ctwa_clid'yi Çıkarın ve Meta Dönüşüm API'sine Gönderin
Webhook alımından Meta Reklam Yöneticisi'nde raporlanabilir çevrimdışı dönüşüme kadar altı adım. Adım 1–3 webhook işleyicinizde; adım 4–6 ise CAPI POST'unda yer alır.
Adım 1: Hemen onaylayın, sonra işleyin. Webhook endpoint'iniz herhangi bir asenkron işlem başlamadan önce 200 döndürmelidir. Whapi.Cloud zaman aşımına uğrayan webhook'ları yeniden gönderir; bu da yinelenen işleme neden olur. Önce yanıt verin, ardından atıf mantığını yürütün.
Adım 2–3: Çıkarın ve saklayın. Payload'dan context.ad.ctwa'yı okuyun. Yoksa mesaj organiktir: erken çıkın ve CAPI'yi atlayın. Varsa, başka herhangi bir işlem yapmadan önce CRM'inizdeki kişi kaydıyla birlikte saklayın. CAPI asenkron olarak çağrılabilir; CAPI çağrısı başarısız olursa hiçbir lead kaybolmaması için CRM kaydı eş zamanlı olarak oluşturulmalıdır.
// Node.js / Express — webhook handler
app.post('/webhook', async (req, res) => {
res.sendStatus(200); // Step 1: acknowledge before processing
const messages = req.body.messages || [];
for (const msg of messages) {
if (msg.from_me) continue; // skip outbound messages
const ctwaClid = msg.context?.ad?.ctwa; // Step 2: ctwa_clid
const convToken = msg.context?.conversion?.data; // deduplication token
const adId = msg.context?.ad?.source?.id; // creative-level attribution
if (!ctwaClid) continue; // organic message — no CAPI event
// Step 3: persist lead in CRM before calling CAPI
await crm.createLead({
phone: msg.from,
name: msg.from_name,
ctwa_clid: ctwaClid,
ad_id: adId,
source: 'whatsapp_ctwa',
});
// Steps 4–6: report offline conversion to Meta CAPI
await sendToMetaCAPI({ ctwaClid, convToken, phone: msg.from });
}
});Adım 4–6: CAPI etkinliğini oluşturun ve POST gönderin. Meta Dönüşüm API'si endpoint'i https://graph.facebook.com/v19.0/{PIXEL_ID}/events'tir. Form gönderimine eşdeğer CTWA akışları için olay adı olarak Lead kullanın: bu Meta'nın algoritması için doğru optimizasyon sinyalidir. ctwa_clid'yi user_data.ctwa_clid olarak, context.conversion.data'yı ise event_id olarak geçirin.
// Steps 4–6: Meta Conversions API POST
async function sendToMetaCAPI({ ctwaClid, convToken, phone }) {
const pixelId = process.env.META_PIXEL_ID;
const accessToken = process.env.META_CAPI_TOKEN;
const payload = {
data: [
{
event_name: 'Lead', // use 'Lead' for CTWA qualification flows
event_time: Math.floor(Date.now() / 1000),
event_id: convToken, // dedup token from context.conversion.data
action_source: 'business_messaging',
user_data: {
ctwa_clid: ctwaClid, // ctwa_clid from context.ad.ctwa
ph: hashSHA256(phone), // hashed phone (SHA-256, no leading +)
},
},
],
};
const url = `https://graph.facebook.com/v19.0/${pixelId}/events?access_token=${accessToken}`;
const resp = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
return resp.json();
}Meta etkinliği aldıktan sonra dönüşüm, Reklam Yöneticisi'nde atıflı bir çevrimdışı etkinlik olarak görünür. Bu durum doğrudan kampanyanızın raporlanan ROAS'ını besler. Atıf penceresi Meta hesabı ayarlarınıza göre belirlenir (varsayılan: 7 günlük tıklama, 1 günlük görüntülenme).
Raporlama hatalarını önleyen üç uygulama detayı:
-
Telefon numarasını hash'leyin. Meta, CAPI'ye iletilen PII alanlarının SHA-256 ile hash'lenmesini zorunlu kılar. Hash'lemeden önce baştaki "+" işaretini kaldırın; ham diziye dahil etmeyin.
-
Bir tarayıcı pikseli kullanıyorsanız event_id zorunludur. Hem sunucu tarafı CAPI hem de tarayıcı pikseli aynı dönüşüm için tetiklendiğinde Meta
event_idkullanarak tekilleştirir. Bu alanı atlarsanız aynı lead raporlarınızda iki kez sayılabilir; bu da dönüşümleri şişirir ve kampanya optimizasyon sinyallerini bozar. -
İşlem onaylanmadıkça
Purchasekullanmayın. İlk temas nitelendirmesi içinLeadkullanın.Purchase'ı yalnızca WhatsApp konuşmasında ödeme alındığı akışlar için saklayın. Yanlış eşleşen olay adları Meta'nın teklif algoritmasına hatalı sinyaller gönderir ve bu durum sonraki kampanya döngülerinde yanlış sonuç için optimizasyona yol açar.
ctwa_clid Atıfı için Pratik Kullanım Örnekleri
ctwa_clid atıfının pazarlama bütçelerinin nasıl dağıtıldığını doğrudan değiştirdiği üç senaryo.
| Kullanım Örneği | Çıkardığınız Alan | İş Sonucu |
|---|---|---|
| CRM'de lead kaynağı takibi | Oluşturma sırasında kişi kaydıyla saklanan context.ad.ctwa |
Satış ekibi her lead'i hangi kampanyanın oluşturduğunu görür; pazarlama, manuel etiketleme sistemi olmadan kapalı döngü ROAS verisi elde eder |
| Kreatif düzeyinde optimizasyon | Konuşmadan satışa dönüşüm oranıyla eşlenen context.ad.source.id |
Hangi reklam kreatiflerinin nitelikli konuşmalar, hangilerinin yüksek hacimli ancak niteliksiz konuşmalar ürettiğini belirleyin; bütçeyi gelir üreten varyantlara taşıyın |
| Meta'ya çevrimdışı dönüşüm raporlama | CAPI'ye Lead etkinliği olarak gönderilen ctwa_clid |
Meta'nın optimizasyon algoritması WhatsApp'tan gerçek aşağı yönlü dönüşüm sinyalleri alır; bu durum sonraki kampanya döngülerinde hedef kitle kalitesini iyileştirir |
Webhook'ta context.ad Eksikse Ne Olur?
Her gelen mesaj bir reklamdan gelmez. Organik kişiler numaranızı ağızdan ağza tavsiye, paylaşılan bağlantılar, QR kodlar veya doğrudan arama yoluyla bulur ve mesajları referral verisi taşımaz.
Whapi.Cloud'da bu kolayca tespit edilebilir: payload'da context.ad yoksa reklam atıfı da yoktur. Herhangi bir CAPI mantığından önce koruma ekleyin:
// Attribution guard — always run this check first
const ctwaClid = msg.context?.ad?.ctwa;
if (!ctwaClid) {
// Organic contact — create CRM record normally, skip CAPI
return;
}
// Attribution confirmed — proceed with CAPI reporting
Geçerli bir ctwa_clid olmadan CAPI etkinliği göndermek Meta Reklam Yöneticisi'nde atıf gürültüsü yaratır ve raporlanan dönüşüm sayısını şişirir. Organik kişiler değerlidir — sadece reklam atıfı taşımaz; bu, nasıl geldiklerinin doğru bir yansımasıdır.
Whapi.Cloud, tam Click-to-WhatsApp atıf zincirini — ctwa_clid, tekilleştirme token'ı ve reklam kreatif kimliği — varsayılan olarak uygun her webhook'ta sunar. ctwa_clid artı Meta CAPI, WhatsApp odaklı satış ekipleri için kanıtlanabilir ve raporlanabilir ROAS anlamına gelir. Mevcut WhatsApp API sağlayıcınız bu verileri sunmuyorsa her CTWA reklam harcaması, ölçülebilir getirisi olmayan bir kara kutudur.
