Lead Ads API: от события leadgen до вашей CRM
Lead Ads — форма заявки, которая заполняется прямо в Instagram или Facebook. После отправки Meta присылает на ваш endpoint вебхук leadgen, в котором только идентификаторы. С Socialift SDK ваш бэкенд проверяет подпись (verify_request), забирает ответы через fb.lead(), нормализует их и записывает заявку в CRM через её API — сразу после получения события.
Обновлено:
Зачем нужна интеграция Lead Ads
Формы Meta Lead Ads складывают заполненные заявки в рекламный кабинет, откуда их можно выгрузить вручную в CSV. Интеграция убирает этот шаг: ваш бэкенд принимает вебхук leadgen и записывает каждую заявку в CRM вскоре после отправки формы. Разница — во времени ответа: не нужно ждать ежедневной выгрузки.
У ручной выгрузки два недостатка. Первый — задержка: при выгрузке раз в день заявка в среднем ждёт полдня, и конкурент уже успел перезвонить. Второй — лимит 90 дней: Meta позволяет скачать только заявки за последние 90 дней, и пропущенная выгрузка может означать потерю данных.
В заявке, пришедшей через интеграцию, есть ID формы, контекст кампании и заполненные ответы — на этом можно построить корректный отчёт по источникам в CRM.
Путь заявки от рекламы до CRM
Создайте форму
Лид-форма собирается в рекламе Facebook или Instagram. Состав вопросов позже сопоставляется с полями CRM.
Запросите разрешения
Запросите leads_retrieval, pages_show_list, pages_read_engagement, pages_manage_ads, pages_manage_metadata (для вебхука) и ads_management (поля рекламы). Для чужих страниц нужен Advanced Access через App Review.
Подпишитесь на вебхук leadgen
В App Dashboard подпишите объект Page на поле leadgen, затем установите приложение на каждую страницу: fb.subscribe_page(page_id, page_token, fields=["leadgen"]).
Заберите содержимое заявки
В событии только идентификаторы (leadgen_id, form_id, page_id, ad_id). Вызовите fb.lead(leadgen_id, page_token) — он вернёт объект Lead с уже нормализованными ответами (socialift.leads.normalize).
Запишите в CRM и назначьте
Ваш код создаёт лид через API CRM, сохраняет form_id и кампанию как источник и назначает ответственного. Готового коннектора к CRM в Socialift нет.
Что даёт SDK и что делает ваш бэкенд
По событию
Событие приходит вскоре после отправки формы — ждать дневной выгрузки не нужно.
Полные ответы формы
Не только ID, но и все поля, которые заполнил пользователь.
Проверка подписи
verify_request сверяет X-Hub-Signature-256 от Meta с сырым телом запроса — поддельное событие leadgen отсекается до обращения к API.
Ключ дедупликации
У Meta нет ID события, вебхук может прийти повторно; dedupe_key() строит стабильный ключ (leadgen_id) для уникального столбца в вашей базе.
Повторы с обеих сторон
Meta повторяет недоставленный вебхук до 36 часов; вызовы API в SDK повторяются при 429/5xx с экспоненциальной задержкой. Повторная запись в CRM — задача вашей очереди.
Контекст источника
Идентификаторы формы и страницы приходят вместе с заявкой — атрибуция сохраняется.
На что обратить внимание при проектировании потока заявок
- Сопоставьте вопросы формы с полями CRM заранее — менять потом дорого.
- Один человек может заполнить форму дважды: опишите правило объединения по телефону или email.
- Отдельно помечайте тестовые заявки, иначе отчётность будет искажена.
- Сохраняйте время поступления заявки и время первого ответа — это ключевой KPI.
- При отзыве доступа поток заявок останавливается: держите это под мониторингом.
- Если админ страницы настроил Leads Access Manager, выдайте доступ пользователю, чей токен используется, — иначе fb.lead() получит отказ.
Частые вопросы
Как автоматически собирать заявки из Instagram?
Lead Ads в Instagram работают через привязанную страницу Facebook, поэтому Meta присылает событие leadgen для этой страницы. Ваш бэкенд забирает ответы через fb.lead() (leads_retrieval и разрешения страницы) и записывает лид в CRM.
Чем интеграция отличается от выгрузки CSV?
CSV — это вручную и с задержкой, а скачать Meta позволяет только заявки за последние 90 дней. Интеграция забирает каждую заявку по событию. Кроме того, в CSV отделять дубли и тестовые заявки приходится руками.
Какие разрешения нужны для Lead Ads API?
leads_retrieval — для чтения заявок, pages_show_list, pages_read_engagement и pages_manage_ads — для страниц, pages_manage_metadata — для подписки на вебхук, ads_management — для полей рекламы. Для страниц людей без роли в приложении нужен Advanced Access через App Review.
Socialift сам передаёт заявку в CRM?
Нет, запись в CRM делает ваш бэкенд: SDK проверяет подпись, забирает ответы заявки и нормализует их. Готового коннектора к amoCRM, Bitrix24 или другой CRM в Socialift нет. Заявки страниц, подключённых в кабинете, видны в Playground через GET /crm/leads.
Работают ли SDK-методы Lead Ads в бесплатный месяц?
Да. Первые 30 дней токен открывает все возможности SDK, включая lead_forms, leads, lead и ad_context. Дальше токен продлевается 30-дневными периодами с баланса, и возможности зависят от плана токена — точный список показывает «Tekshirish va muhitlar» (проверка и окружения) в кабинете. Playground в кабинете работает независимо от плана.
Источники
Связанные страницы
Перестаньте терять заявки
Получите токен, подключите страницу и попробуйте методы заявок в Playground.
Получить бесплатный токен →