Kommo WhatsApp Conversions

Минимальный WordPress-плагин для подтверждённых WhatsApp-конверсий через Kommo. Событие GA4 kommo_whatsapp_lead создаётся только после входящего текстового сообщения с действующим восьмисимвольным кодом обращения, который сопоставляется с внутренним intent token KWC-XXXXXXXX.

Переход на /go-whatsapp, открытие приложения или чата не являются конверсией.

Требования

• WordPress 6.0+ и PHP 8.0+;
• опубликованная страница WordPress со slug go-whatsapp;
• WhatsApp-канал и account webhook в Kommo;
• GA4 web stream;
• HTTPS для сайта и REST endpoint;
• WooCommerce необязателен. При его наличии используется Action Scheduler, иначе WP-Cron.

Установка

1. Скопируйте каталог kommo-whatsapp-leads в wp-content/plugins/.
2. Активируйте Kommo WhatsApp Conversions в WordPress.
3. Создайте или сохраните опубликованную страницу go-whatsapp.
4. Добавьте константы в wp-config.php перед строкой остановки редактирования:

define( 'KWC_PHONE_NUMBER', 'YOUR_WHATSAPP_NUMBER' );
define( 'KWC_KOMMO_WEBHOOK_SECRET', 'replace-with-a-long-random-secret-at-least-48-characters' );
define( 'KWC_GA4_MEASUREMENT_ID', 'G-XXXXXXXXXX' );
define( 'KWC_GA4_API_SECRET', 'replace-with-ga4-api-secret' );

define( 'KWC_ALLOWED_ORIGINS', '' );
define( 'KWC_DEBUG', false );

KWC_PHONE_NUMBER задаётся в международном формате только цифрами. Секрет webhook должен содержать минимум 48 символов. Секреты не сохраняются в базе данных и не показываются в административном интерфейсе.

/go-whatsapp

Используйте существующие ссылки:

/go-whatsapp?from=header
/go-whatsapp?from=footer
/go-whatsapp?from=product

Поддерживаются header, footer, product, cart, checkout, contact, mobile-menu, single-product, archive-product и unknown. Неизвестное значение заменяется на unknown.

Плагин создаёт intent на 7 дней, читает gclid, gbraid и wbraid сначала из query string, затем из уже существующих first-party cookies. Глобальный сбор этих параметров не выполняется: текущий GTM Custom HTML tag продолжает хранить cookies 90 дней. Из _ga и measurement cookie читаются GA4 Client ID и Session ID. В WhatsApp передаётся только текст:

Mi código de atención es XXXXXXXX

Настройка Kommo

1. Откройте Settings → Integrations → Web hooks.
2. Добавьте URL:

https://example.com/wp-json/kommo-whatsapp-conversions/v1/webhook/REPLACE_WITH_LONG_RANDOM_SECRET

3. Выберите событие Incoming message received.
4. Сохраните webhook.
5. Значение VERY_LONG_SECRET должно точно совпадать с KWC_KOMMO_WEBHOOK_SECRET.

Endpoint принимает только POST, проверяет секрет через hash_equals() и ограничивает тело 256 KB. Основной формат Kommo — application/x-www-form-urlencoded; JSON поддерживается как fallback для локальной проверки. Исходящие сообщения, сообщения Salesbot, сообщения без token и повторные доставки подтверждаются HTTP 200, но не создают конверсию.

Точное значение origin зависит от подключённого WhatsApp-провайдера. Сначала оставьте KWC_ALLOWED_ORIGINS пустым. После первого реального сообщения включите KWC_DEBUG, проверьте безопасную запись, добавьте обнаруженное значение, например:

define( 'KWC_ALLOWED_ORIGINS', 'whatsapp,waba' );

После проверки структуры add[] и origin отключите KWC_DEBUG.

GA4 и Google Ads

1. Укажите Measurement ID web stream в KWC_GA4_MEASUREMENT_ID.
2. Создайте Measurement Protocol API secret и укажите его в KWC_GA4_API_SECRET.
3. Выполните подтверждённую тестовую переписку.
4. Найдите kommo_whatsapp_lead в GA4 и отметьте событие как key event.
5. Свяжите GA4 с Google Ads и импортируйте key event.

В GA4 отправляются только session_id при наличии, engagement_time_msec, whatsapp_source, source_path, lead_type=message и provider=kommo. Token, рекламные идентификаторы, contact ID, sender hash, message ID, origin и текст сообщения не передаются. Google Ads API не используется.

Отчёт и обслуживание

Отчёт расположен в WooCommerce → Kommo WhatsApp Leads или Инструменты → Kommo WhatsApp Leads, если WooCommerce выключен. Он показывает cohort по дате создания intent, агрегаты и последние 20 подтверждённых обращений без PII.

Ежедневное обслуживание переводит просроченные pending intents в expired и восстанавливает потерянные pending GA4 jobs. Converted intents автоматически не удаляются. Деактивация удаляет только расписание, а uninstall сохраняет таблицу.

Безопасность и ограничения

• contact ID хранится только как HMAC-SHA256 с wp_salt( 'auth' );
• текст сообщения, contact/chat/talk IDs, телефон, имя и raw webhook не сохраняются;
• debug не содержит token, cookies, PII или секреты;
• звонки WhatsApp не поддерживаются;
• OAuth Kommo, Meta webhook, Google Ads API и повторная отправка failed GA4 событий не реализованы;
• фактические origin и структура add[] должны быть подтверждены первым реальным webhook.

English

This plugin records a conversion only after Kommo delivers an incoming WhatsApp text message containing a valid eight-character attention code mapped to an active internal KWC-XXXXXXXX intent token. /go-whatsapp stores attribution and GA identifiers, opens a fixed wa.me destination, and does not emit a conversion by itself.

Configure the constants shown above, create the published go-whatsapp page, and add the POST webhook URL under Kommo Settings → Integrations → Web hooks for Incoming message received. Keep KWC_ALLOWED_ORIGINS empty until a real provider-specific origin has been observed safely. GA4 delivery runs through Action Scheduler when WooCommerce is available and falls back to WP-Cron.

The plugin intentionally stores no message text, customer phone number, raw payload, Kommo contact ID, or secrets. Its first release does not support calls, Kommo OAuth, Meta webhooks, Google Ads API, or automatic retries for failed GA4 requests.