TL;DR: Whapi.Cloud включает ctwa_clid в каждый webhook Click-to-WhatsApp под context.ad.ctwa без какой-либо настройки с вашей стороны. Прочитайте значение, сохраните в CRM, затем отправьте POST-запрос в Meta Conversions API как user_data.ctwa_clid, чтобы ваши расходы на рекламу в WhatsApp стали атрибутируемыми. Если context.ad отсутствует — сообщение органическое: пропустите отчёт в CAPI для этого события. Используйте Lead как название события по умолчанию.
Что такое реклама Click-to-WhatsApp?
Реклама Click-to-WhatsApp (CTWA) — это форматы объявлений Meta в Facebook и Instagram. Нажатие на кнопку призыва к действию сразу открывает разговор в WhatsApp без промежуточной посадочной страницы или формы.
Пользователь нажимает на объявление, WhatsApp открывается, и его первое сообщение попадает прямо в вашу входящую папку. Оказавшись в WhatsApp, стандартный браузерный пиксель уже не может отследить пользователя. До появления ctwa_clid все расходы на рекламу в WhatsApp фактически не поддавались атрибуции: лид, кликнувший на ваше объявление, был неотличим от того, кто набрал ваш номер вручную.
Что такое ctwa_clid и как это работает?
Когда пользователь нажимает на рекламу Click-to-WhatsApp, Meta внедряет в разговор идентификатор клика ctwa_clid.
Он передаётся с первым входящим сообщением и позволяет связать лида из WhatsApp с конкретным объявлением, кампанией и сегментом аудитории, которые его сгенерировали.
В отличие от click ID в UTM-метках, ctwa_clid хранится в метаданных сообщения, а не в query-параметре URL. Meta генерирует его в момент нажатия на объявление и прикрепляет к объекту referral первого входящего сообщения.
Whapi.Cloud нативно передаёт ctwa_clid в каждом подходящем входящем webhook-е через context.ad.ctwa. Никакой настройки с вашей стороны: ни специальных флагов, ни дополнительных API-вызовов. Некоторые провайдеры удаляют или не включают объект referral до того, как payload достигает вашего обработчика. Whapi.Cloud передаёт полный объект атрибуции по умолчанию.
Три поля атрибуции приходят вместе в одном событии webhook-а:
-
context.ad.ctwa: само значение
ctwa_clid. Это идентификатор, который вы отправляете в Meta Conversions API какuser_data.ctwa_clidдля отчёта об офлайн-конверсии. -
context.conversion.data: токен дедупликации. Передайте его как
event_idв payload CAPI. Если ваша настройка также запускает браузерный пиксель для той же сессии, Meta использует этот токен для дедупликации серверных и клиентских событий, чтобы конверсия считалась один раз, а не дважды. -
context.ad.source.id идентифицирует конкретный рекламный креатив. Используйте его вместе с
ctwa_clid, когда нужна атрибуция на уровне креатива: не просто «этот лид пришёл из кампании X», а «этот лид пришёл из варианта карусели с конкретным заголовком и изображением».
Предварительные требования: три условия для получения ctwa_clid
Все три условия должны выполняться, прежде чем ctwa_clid появится в ваших webhook-ах. Нарушение любого из них означает, что context.ad будет отсутствовать, независимо от того, как написан ваш обработчик webhook-а.
- Активная кампания Click-to-WhatsApp. Входящее сообщение должно исходить от нажатия на CTWA-объявление. Органические контакты (пользователи, нашедшие ваш номер через поиск, общую ссылку или прямой ввод) отправляют сообщения без прикреплённых данных referral.
- Атрибуция включена в настройках WhatsApp Business. Этот шаг чаще всего упускают команды. Откройте настройки аккаунта WhatsApp Business, найдите раздел «Атрибуция рекламы» и включите его. Без этой опции Meta не включает объект referral в разговор, и
context.adникогда не появляется в payload webhook-а. - Настроенный endpoint webhook-а Whapi.Cloud. URL вашего backend-а должен быть зарегистрирован в панели управления Whapi.Cloud и доступен публично. Стандартная настройка webhook-а применима: никаких специальных режимов атрибуции или дополнительных разрешений на стороне Whapi.Cloud не требуется.
Webhook Whapi.Cloud: где находится ctwa_clid
Когда приходит сообщение с атрибуцией CTWA, Whapi.Cloud доставляет payload webhook-а, включающий объект context рядом со стандартными полями сообщения. Этот объект имеет два подключа: ad (данные источника клика) и conversion (токен дедупликации).
Ниже представлен полный payload webhook-а Whapi.Cloud для сообщения Click-to-WhatsApp с атрибуцией. Изучите блок context: всё необходимое для отчётности в CAPI находится там.
{
"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"
}
]
}Два пути, которые нужно запомнить: messages[0].context.ad.ctwa — это ctwa_clid. messages[0].context.conversion.data — токен дедупликации. Оба необходимы для полного payload CAPI.
context.ad.source.id также передаётся в том же webhook-е: это ID рекламного креатива. Одно событие webhook-а одновременно доставляет и атрибуцию на уровне пользователя (ctwa_clid), и атрибуцию на уровне креатива (ID объявления). Никаких дополнительных API-вызовов не требуется, чтобы узнать, какой креатив увидел пользователь.
Полный справочник полей и примеры граничных случаев см. в статье базы знаний Whapi.Cloud об отслеживании лидов WhatsApp из рекламы Meta. Полная спецификация payload входящего webhook-а, включая все поля context, — в справочнике формата входящих webhook-ов.
Пошагово: извлеките ctwa_clid и отправьте в Meta Conversions API
Шесть шагов от получения webhook-а до отчётной офлайн-конверсии в Meta Ads Manager. Шаги 1–3 выполняются в обработчике webhook-а; шаги 4–6 — это POST в CAPI.
Шаг 1: немедленно подтвердите получение, затем обрабатывайте. Ваш endpoint webhook-а должен вернуть 200 до начала любой асинхронной работы. Whapi.Cloud повторно отправляет webhook-и, у которых истёк таймаут, что создаёт дублирующуюся обработку. Сначала ответьте, затем выполняйте логику атрибуции.
Шаги 2–3: извлеките и сохраните. Прочитайте context.ad.ctwa из payload. Если отсутствует — сообщение органическое: выйдите раньше и пропустите CAPI. Если присутствует — сохраните его вместе с записью контакта в вашем CRM до выполнения любых других действий. CAPI можно вызвать асинхронно; запись CRM должна создаваться синхронно, чтобы ни один лид не был потерян при сбое вызова CAPI.
// 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 });
}
});Шаги 4–6: сформируйте и отправьте POST-запрос с событием CAPI. Endpoint Meta Conversions API — https://graph.facebook.com/v19.0/{PIXEL_ID}/events. Используйте Lead как название события для CTWA-потоков, эквивалентных отправке форм: это правильный сигнал оптимизации для алгоритма Meta. Передайте ctwa_clid как user_data.ctwa_clid, а context.conversion.data — как event_id.
// 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 получает событие, конверсия появляется в Ads Manager как атрибутированное офлайн-событие. Это напрямую влияет на отчётный ROAS вашей кампании. Окно атрибуции следует настройкам вашего аккаунта Meta (по умолчанию: 7 дней по клику, 1 день по просмотру).
Три детали реализации, которые предотвращают ошибки в отчётности:
-
Хешируйте номер телефона. Meta требует, чтобы PII-поля, передаваемые в CAPI, были хешированы SHA-256. Уберите ведущий знак «+» перед хешированием; не включайте его в исходную строку.
-
event_id обязателен, если вы используете браузерный пиксель. Когда и server-side CAPI, и браузерный пиксель срабатывают для одной конверсии, Meta дедуплицирует их по
event_id. Пропустите это поле — и тот же лид может быть посчитан дважды в ваших отчётах, завышая конверсии и искажая сигналы оптимизации кампании. -
Не используйте
Purchase, если транзакция не подтверждена. ИспользуйтеLeadдля квалификации первого контакта. ОставьтеPurchaseдля потоков, где платёж собирается внутри разговора в WhatsApp. Неправильные названия событий отправляют неверные сигналы алгоритму ставок Meta, который оптимизируется под неправильный результат в последующих циклах кампании.
Практические сценарии применения атрибуции ctwa_clid
Три сценария, где атрибуция с ctwa_clid напрямую меняет распределение маркетинговых бюджетов.
| Сценарий использования | Извлекаемое поле | Бизнес-результат |
|---|---|---|
| Отслеживание источника лидов в CRM | context.ad.ctwa, сохранённый с записью контакта при создании |
Отдел продаж видит, какая кампания сгенерировала каждого лида; маркетинг получает данные ROAS замкнутого цикла без ручной системы тегирования |
| Оптимизация на уровне креатива | context.ad.source.id, сопоставленный с коэффициентом конверсии разговора в продажу |
Определите, какие рекламные креативы генерируют квалифицированные разговоры, а какие — большой объём неквалифицированных; перераспределите бюджет на варианты, приносящие доход |
| Отчётность офлайн-конверсий для Meta | ctwa_clid, отправленный в CAPI как событие Lead |
Алгоритм оптимизации Meta получает реальные сигналы конверсии из WhatsApp, что улучшает качество целевой аудитории в последующих циклах кампании |
Что делать, если context.ad отсутствует в webhook-е?
Не каждое входящее сообщение приходит из рекламы. Органические контакты находят ваш номер через сарафанное радио, общие ссылки, QR-коды или прямой поиск, и их сообщения не содержат данных referral.
В Whapi.Cloud это легко определить: если context.ad отсутствует в payload, атрибуция рекламы отсутствует. Добавьте проверку перед любой логикой CAPI:
// 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
Отправка события CAPI без действительного ctwa_clid создаёт шум атрибуции в Meta Ads Manager и завышает отчётные счётчики конверсий. Органические контакты ценны — они просто не несут атрибуции рекламы, что является точным отражением того, как они пришли.
Whapi.Cloud раскрывает полную цепочку атрибуции Click-to-WhatsApp — ctwa_clid, токен дедупликации и ID рекламного креатива — в каждом подходящем webhook-е по умолчанию. ctwa_clid плюс Meta CAPI — это доказуемый и отчётный ROAS для команд продаж, работающих через WhatsApp. Если ваш текущий провайдер WhatsApp API не раскрывает эти данные, каждый рубль расходов на рекламу CTWA — это чёрный ящик без измеримого возврата.
