Conversions API

Conversions API (CAPI) показывает Meta конверсии, которые происходят вне браузера: заказы, подтверждённые на сервере, лиды, квалифицированные в CRM, покупки в офлайн-точке. AdWitch берёт интеграцию на себя: вы отправляете события, AdWitch проверяет их, нормализует и хэширует SHA-256 те поля сопоставления, которые Meta ожидает в виде хэша, убирает дубликаты и передаёт в ваш пиксель.

Два входа:

Хостинговый приём — один URL и ключ на рекламный кабинет; ваш бэкенд или CRM отправляет на него события в формате ниже.
Загрузка из чата — «загрузи эти покупки как офлайн-конверсии» с таблицей или CSV; агент захэширует строки и отправит их после вашего подтверждения.

Обоим нужен пиксель по умолчанию у кабинета (страница «Рекламные кабинеты», /accounts) и принятые администратором вашего бизнеса Business Tools Terms на стороне Meta.

Магазины на Shopify, WooCommerce, BigCommerce, Wix или Tilda

Магазину или сайту на одной из этих платформ приём не нужен: официальная интеграция платформы уже отправляет в Meta серверные события (Conversions API) рядом с браузерным пикселем. Проверка Сигнал и событие оптимизации на странице «Рекламные кабинеты» узнаёт эти платформы по домену, на котором срабатывает пиксель, и показывает эти же шаги, если до Meta доходят только браузерные события, — а на Shopify, WooCommerce и BigCommerce, чьи интеграции передают ещё и данные покупателей, и когда сопоставление покупателей слабое.

Shopify — бесплатное приложение Meta Facebook & Instagram:

В админке Shopify откройте Sales channels → Facebook & Instagram → Settings → Data sharing settings.
В разделе Customer data sharing включите обмен данными покупателей и выберите уровень Maximum (Conversions API + пиксель Meta).
Подключите пиксель Meta, который привязан в AdWitch как пиксель по умолчанию рекламного кабинета.
Удалите другие приложения для пикселя и код пикселя Meta, вручную добавленный в тему, чтобы события не считались дважды.

Подробнее — в справке Shopify (на английском).

WooCommerce — бесплатный официальный плагин Meta for WooCommerce (раньше Facebook for WooCommerce):

Установите и активируйте плагин из каталога плагинов WordPress.
Подключите его к Meta и выберите пиксель Meta, привязанный в AdWitch.
Не выключайте в плагине Conversions API (серверные события).
Удалите другие плагины для пикселя и код пикселя Meta, вручную добавленный в тему.

BigCommerce — встроенная интеграция с пикселем Meta, которая без доплаты отправляет ещё и события Conversions API с захешированными данными покупателей (email, телефон, имя):

В панели управления BigCommerce откройте Settings › Data Solutions и в блоке Web analytics нажмите Connect рядом с Meta Pixel.
Нажмите Connect with Meta Pixel, войдите в Facebook и выберите Business Manager, страницу Facebook и пиксель Meta, привязанный в AdWitch.
На экране What is BigCommerce allowed to do оставьте включёнными все опции.
Удалите другие приложения для пикселя и код пикселя Meta, вручную добавленный в тему или скрипты.

Подробнее — в справке BigCommerce (на английском).

Wix — встроенная интеграция «Пиксель Meta и CAPI», которая отправляет события с серверов Wix. Для неё нужны премиум-план, подключённый домен и домен, подтверждённый в Meta:

В панели управления сайтом откройте «Инструменты маркетинга» и нажмите «Подключить» в разделе «Пиксель Meta и CAPI». Если там только старая интеграция «Пиксель Meta», удалите её, обновите страницу и подключите «Пиксель Meta и CAPI».
Нажмите «Подключить к Facebook», войдите в аккаунт и, когда спросят про пиксель, выберите пиксель Meta, привязанный в AdWitch.
Удалите код пикселя Meta, вручную добавленный на сайт (пользовательский код).

Подробнее — в справке Wix.

Tilda — встроенное подключение Conversions API, которое отправляет в Meta заявки с форм (Lead) и оплаты из корзины (Purchase) с сервера Tilda:

В Events Manager откройте пиксель Meta, привязанный в AdWitch, перейдите в его настройки и в разделе Conversions API нажмите «Сгенерировать маркер доступа».
В Tilda откройте Настройки сайта → Формы → Facebook Conversion API, вставьте ID пикселя и маркер доступа и сохраните.
В «Контенте» каждой формы, заявки с которой должны доходить до Meta, включая корзину, отметьте приёмщик данных Facebook Conversion API, затем переопубликуйте эти страницы.
Удалите другой код пикселя Meta, вручную добавленный на сайт.

Подробнее — в справке Tilda.

Отправляете те же покупки ещё и через приём? Тогда они посчитаются дважды, если оба пути не передают для одного заказа одинаковый event_id (с тем же event_name).

Вебхуки этих платформ, направленные на URL приёма, не работают: они не в формате серверных событий Meta, поэтому приём отвечает 400 DATA_REQUIRED (или 401, если в запросе нет ключа) и ничего не записывает. Если такие запросы приходят с вашим ключом приёма, заметка «Последняя проблема» в разделе Conversions API на карточке кабинета сообщит об этом — с названием платформы, когда запрос его выдаёт, — и даст ссылку на этот раздел. Удалите эти вебхуки в самой платформе и подключите её официальную интеграцию, описанную выше.

Настройка приёма

Откройте «Рекламные кабинеты» (/accounts) и разверните Conversions API на карточке кабинета.
Нажмите Создать ключ приёма. Ключ (capi_<id>_<secret>, где ID — 12 шестнадцатеричных символов, а секрет — 48) показывается один раз — сохраните его в бэкенде сразу; AdWitch хранит только хэш. Потеряли? Перевыпустить ключ выдаст новый и тут же отключит старый.
При желании задайте код тестового события (Events Manager → Тестовые события). Пока он задан, каждая партия попадает во вкладку тестовых событий, а не в боевую отчётность — уберите его перед запуском.
Скопируйте пример curl или JSON вебхука и отправьте первое событие.

В разделе видны счётчики за 24 часа (получено, передано, отклонено проверкой, дубликаты, отклонено Meta), последние партии и последняя проблема. Принимать события ставит приём на паузу без отзыва ключа (отправители получают 403 CAPI_DISABLED); Отозвать ключ останавливает его насовсем (401 KEY_REVOKED).

Ключами управляют только владельцы и администраторы команды; остальные участники видят статус.

Контракт приёма

POST https://api.adwitch.ai/api/capi/v1/events
Authorization: Bearer capi_<id>_<secret>      (или X-Capi-Key: …)
Content-Type: application/json

Тело — стандартная форма серверных событий Meta: data[] с событиями (голый массив тоже принимается) и необязательный test_event_code уровня запроса, который перекрывает сохранённый в настройках:

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1757600000,
      "action_source": "website",
      "event_source_url": "https://shop.example.com/checkout/thank-you",
      "event_id": "order-10045",
      "user_data": {
        "em": "customer@example.com",
        "ph": "+34600000000",
        "client_ip_address": "203.0.113.5",
        "client_user_agent": "Mozilla/5.0",
        "fbp": "fb.1.1700000000000.123456789"
      },
      "custom_data": { "value": 49.9, "currency": "EUR", "order_id": "10045" }
    }
  ],
  "test_event_code": "TEST12345"
}

Правила для каждого события:

Поле	Правило
`event_name`	Обязательно. Стандартные имена (`Purchase`, `Lead`, `CompleteRegistration`, …) или своё.
`event_time`	Unix-секунды (миллисекунды и ISO-даты тоже принимаются). Не старше 7 дней и не более чем на 10 минут в будущем.
`action_source`	`website`, `email`, `app`, `phone_call`, `chat`, `physical_store`, `system_generated`, `other`. Для `website` нужен ещё `event_source_url`; для `app` — `app_data` (`advertiser_tracking_enabled` 0 или 1 и `extinfo` с платформой `a2`/`i2` и версией ОС), и такие события засчитываются, только если пиксель кабинета — это набор данных, привязанный к приложению. `business_messaging` здесь не принимается (`business_messaging_not_accepted`): такие события передаются в набор данных Страницы, аккаунта WhatsApp Business или аккаунта Instagram, а не в пиксель; отправляйте их через чат (см. ниже).
`event_id`	Рекомендуется — это ваш ключ идемпотентности. Если нет, из события выводится детерминированный id, и повтор запроса не удвоит конверсии.
`user_data`	Хотя бы один сопоставимый идентификатор (`em`, `ph`, `external_id`, `fbp`/`fbc`, `lead_id`, IP + user agent или имя + город/индекс/дата рождения). Длинные имена (`email`, `phone`, `first_name`, …) понимаются.
`custom_data`	Для `Purchase` нужны `value` и `currency` (валюта кабинета подставляется, если её нет).

Хэширование. em, ph, fn, ln, ge, db, ct, st, zp, country и external_id нормализуются (нижний регистр, обрезка пробелов, телефон — только цифры с кодом страны, …) и хэшируются SHA-256 на стороне AdWitch. Значение, которое уже является 64-символьным SHA-256, передаётся как есть. client_ip_address, client_user_agent, fbp, fbc, lead_id и другие идентификаторы, которые Meta ждёт в открытом виде, передаются без хэширования.

Дедупликация. Одинаковые event_name + event_id в течение 48 часов по одному кабинету отбрасываются и отражаются в duplicates — это покрывает и ваши повторы, и случай, когда одни и те же заказы пришли и через приём, и загрузкой из чата.

Лимиты. До 1000 событий и 1 МБ на запрос; 600 запросов в минуту на ключ и 1200 в минуту на IP-адрес. Больше — делите партию.

Ответы

202 Accepted — что-то поставлено в очередь для Meta; 200 OK — передавать нечего (все строки отклонены или дубликаты). В обоих случаях:

{
  "status": "queued",
  "batch_id": 812,
  "pixel_id": "555000111",
  "received": 4,
  "accepted": 2,
  "rejected": [{ "index": 2, "reason": "event_time_invalid", "field": "event_time", "message": "…" }],
  "duplicates": [{ "index": 3, "reason": "duplicate_event_id", "field": "event_id", "message": "an event with the same event_name and event_id was already accepted in the last 48 hours" }],
  "accepted_event_ids": [{ "index": 0, "event_id": "order-10045" }, { "index": 1, "event_id": "order-10046" }],
  "hashed_user_data_keys": ["em", "ph"],
  "test_event_code": "TEST12345"
}

В отклонённых и повторных строках указаны индекс, причина и сообщение, а при необходимости и поле, но не персональное значение. Если в очередь ничего не попало, status равен nothing_to_forward, а batch_id — null. test_event_code присутствует только когда задан.

Статус	`reason`	Значение
401	`KEY_MISSING` / `KEY_INVALID`	Нет ключа, неизвестный ключ или неверный секрет.
401	`KEY_REVOKED`	Ключ отозван в настройках; создайте новый.
403	`CAPI_DISABLED`	«Принимать события» выключено для кабинета.
409	`PIXEL_NOT_BOUND`	У кабинета больше нет пикселя по умолчанию.
409	`FB_NOT_CONNECTED`	Подключение к Meta потеряно; переподключите кабинет.
400	`DATA_REQUIRED` / `TOO_MANY_EVENTS`	Нет `data[]` или больше 1000 событий. Если тело не в формате Meta, в ответе есть `hint` и `docs`, а если это вебхук одной из платформ выше — ещё `platform` и `topic`.
429	`RATE_LIMITED`	Сбавьте темп; `Retry-After` подскажет когда.

Передача асинхронна: статус партии (forwarded, partial, failed, terms_required) и предупреждения Meta по событиям видны в Последних партиях кабинета. Если Meta отказала из-за непринятых Business Tools Terms, в разделе появится уведомление со ссылкой на бизнес; повторов не будет, пока администратор их не примет.

Загрузка конверсий из чата

Попросите агента, например: «Загрузи эти покупки как офлайн-конверсии» и вставьте таблицу или приложите CSV с колонками вроде email, телефон, заказ, сумма, валюта, дата (заголовки на русском, английском и испанском распознаются). Агент:

нормализует и хэширует строки локально и показывает, что было бы отправлено (dry_run): сколько строк, какие идентификаторы захэшированы, какие строки отклонены и почему;
запрашивает ваше явное подтверждение — данные клиентов (в виде хэшей) покидают платформу;
отправляет партиями до 1000 событий на вызов Graph и сообщает events_received и предупреждения Meta;
направляет в Events Manager → Тестовые события (с кодом тестового события) или Обзор; get_pixel_diagnostics покажет поступающие события.

Загрузки из чата делят 48-часовое окно дедупликации с приёмом по вебхуку.

Продажи в чатах Messenger, WhatsApp и Instagram

Покупки и квалифицированные лиды, полученные в переписке после рекламы с переходом в сообщения, передаются через Conversions API for Business Messaging. Тогда Meta может оптимизировать рекламу с переходом в Messenger и WhatsApp под покупки в чатах (цель «покупки в сообщениях»); события Instagram служат только для измерения. В каждой строке нужен messaging_channel (whatsapp, messenger или instagram) и пара идентификаторов этого чата:

Канал	Аккаунт	Собеседник
`whatsapp`	`whatsapp_business_account_id`	`ctwa_clid` (из вебхука рекламы с переходом в WhatsApp)
`messenger`	`page_id`	`page_scoped_user_id` (PSID)
`instagram`	`ig_account_id`	`ig_sid` (IGSID)

Поддерживаемые события: Purchase, LeadSubmitted, QualifiedLead, InitiateCheckout, AddToCart, ViewContent, OrderCreated, OrderShipped, OrderDelivered, OrderCanceled, OrderReturned, CartAbandoned, RatingProvided, ReviewProvided. Одна загрузка — один канал и один аккаунт. События уходят в набор данных этой Страницы, аккаунта WhatsApp Business или аккаунта Instagram (он создаётся, если его нет), а не в пиксель. Строка без канала, с неизвестным каналом или с отсутствующим либо чужим идентификатором отклоняется с кодом причины. Перед первой отправкой агент показывает дополнительные разрешения Meta (page_events для Messenger; whatsapp_business_management и whatsapp_business_manage_events для WhatsApp; instagram_manage_events для Instagram) и их статус и ничего не отправляет, пока известно, что какого-то из них нет. Meta не убирает дубли таких событий, поэтому каждую продажу загружайте один раз.

Этапы продаж из CRM

Цель оптимизации Конверсионные лиды (QUALITY_LEAD) учится на этапах, которые ваша CRM отмечает у каждого лида. Отправляйте их на точку приёма в CRM-формате Meta — одно событие на каждую смену этапа, с названием этапа:

event_name — этап так, как он называется в CRM (Lead, Qualified, Opportunity, Closed Won, …), включая первый этап — сам лид.
action_source — system_generated.
user_data.lead_id — ID лида Meta из моментальной формы (в Meta это leadgen_id) строкой, ровно так, как его отдала Meta; передаётся без хэширования. Нет ID лида — отправьте email или телефон, по которым идёт сопоставление; AdWitch их хэширует.
custom_data.event_source — crm; custom_data.lead_event_source — название вашей CRM (HubSpot, Salesforce, In-house CRM, …).
event_time — время смены этапа: не старше 7 дней и позже создания лида.

{
  "data": [
    {
      "event_name": "Qualified",
      "event_time": 1757600000,
      "action_source": "system_generated",
      "event_id": "hubspot-1234567890123456-qualified",
      "user_data": { "lead_id": "1234567890123456" },
      "custom_data": {
        "event_source": "crm",
        "lead_event_source": "HubSpot"
      }
    }
  ]
}

Пишите ID в кавычках: 15–17-значный ID лида, записанный числом JSON, могут округлить инструменты, через которые он проходит, и тогда он укажет на другого лида.

Правило 7 дней. Meta принимает этап, только если его event_time не старше 7 дней, поэтому AdWitch отклоняет более старые с причиной event_time_too_old — ежемесячная выгрузка из CRM теряет большую часть этапов. Загружайте смены этапов хотя бы раз в день: сначала с кодом тестового события (Events Manager → Тестовые события), потом без него.

В чате приложите этапы таблицей или CSV с колонками lead_id, event_name, event_time, event_source и lead_event_source и попросите агента отправить их как этапы CRM (action_source system_generated).

Что не входит

Хостинг браузерного сниппета пикселя или JavaScript SDK.
App Events API для SDK (события приложения с вашего сервера идут с action_source app, см. выше), фиды каталогов и устаревший Offline Conversions API (offline event sets).
Собственное приложение или плагин для Shopify, WooCommerce или другой платформы магазина — используйте официальные интеграции, описанные выше.

События учитываются по команде в журнале использования; пока они не тарифицируются.