Conversion API

Conversion API (CAPI) — отправка конверсий с сервера в рекламную площадку. Площадка получает событие «покупка» или «лид» и сопоставляет его с показом объявления. Браузерный пиксель при этом не нужен.

Интеграции не проверены на боевых API

Код отправки написан по публичной документации площадок, но ни одна интеграция не проверялась на боевом API. В интерфейсе это тоже написано. Перед тем как полагаться на CAPI, проверьте события на тестовом пикселе или в тестовом режиме площадки и сверьте, что событие появилось.

Настройка

Откройте «CAPI-интеграции» (/dashboard/capi-integrations) и нажмите «Новая интеграция».

1. Провайдер. Meta, TikTok или Google Ads.
2. Учётные данные. Поля зависят от провайдера, см. вкладки ниже.
3. Маппинг статусов. Сопоставьте наши статусы с названием события площадки, например lead → Lead, sale → Purchase. Статус без маппинга не отправляется.
4. Активна. Включите интеграцию.

После сохранения учётные данные не показываются. Чтобы заменить их, нажмите «Заменить учётные данные» и введите новые значения.

1. Провайдер.
2. Учётные данные провайдера.
3. Переключатель «Активна».

Провайдеры

Meta

Поле	Что вписать
Pixel ID	ID пикселя
Access Token	Токен доступа Conversions API

Отправка идёт в Graph API v26.0 на /{pixel_id}/events. Клик сохраняет fbclid из адреса объявления. Из него строится fbc в формате fb.1.<время в мс>.<fbclid>. Идентификатор посетителя передаётся как SHA-256 от нашего click id.

Осторожно

Meta принимает события не старше 7 дней. Если в одном пакете есть хотя бы одно старое событие, Meta отклоняет весь пакет. Поздние конверсии и импорт задним числом могут не пройти.

Telegfy не передаёт IP-адрес и User-Agent посетителя. Поэтому сопоставление в Meta слабее, чем у пикселя.

TikTok

Поле	Что вписать
Pixel Code	Код пикселя (Events API)
Access Token	Токен доступа

Отправка идёт в Events API v1.3 (event/track). Клик сохраняет ttclid из адреса объявления. Он нужен для сопоставления, без него событие привязывается слабо.

Осторожно

Официальная документация TikTok не открылась при проверке, поэтому обязательные поля сверены не полностью. Проверьте формат запроса на тестовом событии.

Google Ads

Поле	Что вписать
Customer ID	ID аккаунта без дефисов
Conversion Action ID	ID действия конверсии в Google Ads
Developer Token	Токен разработчика
OAuth Client ID и Client Secret	Учётные данные OAuth-приложения
Refresh Token	Долгоживущий токен обновления
Login Customer ID	ID менеджерского аккаунта (MCC). Необязательно.

Отправка идёт в Google Ads API v25 (uploadClickConversions). Telegfy сам получает короткоживущий access token по refresh token. Ещё одно правило: отправляется только конверсия с gclid. Если у клика gclid нет, событие пропускается.

Осторожно

Google Ads принимает офлайн-конверсии только для действия конверсии типа «импорт». Настройте его в Google Ads, прежде чем подключать Telegfy. Как получить refresh token, описано в справке Google, сверьте шаги с ней.

Что уходит и когда

• На каждую конверсию с подходящим статусом создаётся одна отправка на интеграцию. Повторные отправки той же пары (конверсия, интеграция, статус) не создаются.
• Отправка идёт той же очередью, что и исходящие постбеки: раз в минуту, до 6 попыток.
• event_id стабилен для всех повторов. Площадка не засчитает одно событие дважды.
• Статус без маппинга не отправляется, в лог не попадает как ошибка.

Частые ошибки

• Нет fbclid, ttclid или gclid у клика. Сопоставления по клику не будет. Проверьте, что площадка добавляет параметр к адресу ссылки и что ссылка его не теряет по пути. Для Google нужна автопометка.
• Событие не совпадает с целью. В маппинге статусов указано название, которое площадка не знает. Сверьте с каталогом событий в кабинете.
• Google отклоняет событие. Не настроено действие конверсии типа импорт, либо refresh token устарел.

Что читать дальше

• Гайды по рекламным площадкам — как передать fbclid, ttclid и gclid.
• Исходящие постбеки — тот же механизм очереди и повторов.
• Импорт конверсий — если нужно отправить старые конверсии.