Приложение Meta для Facebook и Instagram API: пошаговая настройка

Что даёт приложение Meta?

Основные термины

Use case

Сценарий интеграции, который выбирается при создании приложения (например, «Manage everything on your Page»). От него зависят разрешения и продукты. После создания use case удалить нельзя — можно только добавить совместимый.

Facebook Login for Business

Продукт входа для приложений типа Business. Разрешения выбираются в конфигурации в дашборде, а в код передаётся только её ID (config_id).

Standard и Advanced Access

При Standard Access разрешения могут выдать только люди с ролью в приложении. Для Pages и аккаунтов, которыми вы не управляете, каждому разрешению нужен Advanced Access через App Review.

Business Verification

Подтверждение компании в Meta. Приложение, запрашивающее Advanced Access, должно быть подключено к подтверждённому бизнес-портфолио.

Как создать и настроить приложение Meta

1. 1

   Создайте приложение

   На developers.facebook.com/apps начните создание приложения: укажите название и контактный email, затем выберите use cases (например, «Manage everything on your Page»). Если нужен Facebook Login for Business с config_id, а подходящего сценария в списке нет, выберите «Other», а затем тип приложения Business.

2. 2

   Подключите бизнес-портфолио

   Мастер предложит подключить подтверждённое или неподтверждённое бизнес-портфолио либо создать новое. Подключите компанию, которой будет принадлежать интеграция: именно её потом подтверждают для Advanced Access.

3. 3

   Скопируйте App ID и App Secret

   Оба значения — в App settings → Basic. App ID также виден в верхней части дашборда. Храните секрет в переменных окружения или менеджере секретов.

4. 4

   Добавьте redirect URI

   Добавьте продукт Facebook Login for Business (use case мог добавить его сам). В его настройках впишите адрес callback в Valid OAuth Redirect URIs. При включённом Strict Mode Meta требует точного совпадения: другой путь или query-параметр, которого нет в списке, будут отклонены.

5. 5

   Создайте конфигурацию и получите config_id

   В разделе Configurations создайте конфигурацию (или возьмите шаблон): название, тип токена, бизнес-активы и разрешения. Тип токена — User access token: поток входа Socialift обменивает код на долгоживущий пользовательский токен и затем читает Pages. System user token требует в ссылке входа дополнительный параметр (override_default_response_type), который этот поток не отправляет. Скопируйте Configuration ID.

6. 6

   Добавьте разрешения в use case

   На экране настройки use case добавьте из таблицы ниже только те разрешения, которые интеграция действительно использует. По документации Meta, самая частая причина отказа в App Review — запрос разрешения или функции, которые приложению не нужны.

7. 7

   Настройте вебхуки

   Endpoint должен работать по HTTPS с валидным сертификатом (самоподписанные не принимаются). Укажите Callback URL и Verify token, подтвердите, затем подпишитесь на поля: объект Page — leadgen (Lead Ads) и feed (посты и комментарии); объект Instagram — comments, mentions и messages для Direct. После этого каждая Page должна установить приложение через subscribed_apps — без этого события не приходят.

8. 8

   Добавьте роли и тестировщиков

   В панели Roles пригласите администраторов, разработчиков и тестировщиков. До App Review разрешения могут выдать только люди с ролью в приложении (или в бизнесе, которому оно принадлежит) — так тестируют на своих Pages.

9. 9

   Пройдите App Review и Business Verification

   Для Pages и аккаунтов, которыми вы не управляете, каждому разрешению нужен Advanced Access. На каждое разрешение — отдельное описание и запись экрана (пользователь выдаёт разрешение, приложение его использует); в течение 30 дней до отправки — хотя бы один успешный API-вызов с этим разрешением; URL политики конфиденциальности и иконка 1024×1024. Для Advanced Access обязательна Business Verification.

Как добавить приложение Meta в Socialift

1. 1

   Откройте «Kalitlar» → «Meta (Facebook) app»

   В кабинете откройте раздел «Kalitlar» (ключи) и разверните карточку «Meta (Facebook) app». В боковом блоке «Konsolga ko'chiring» (скопируйте в консоль) Redirect URI виден ещё до сохранения ключа — вставьте его в Valid OAuth Redirect URIs.

2. 2

   Заполните поля

   App ID и App secret обязательны. Configuration ID необязателен: если он заполнен, в ссылку входа уходит config_id, а поле «Scope'lar» не используется. Для приложения Consumer оставьте его пустым — тогда отправляется список scope (пустое «Scope'lar» = стандартный список, через запятую или пробел).

3. 3

   Нажмите «Saqlash va tekshirish» (сохранить и проверить)

   Socialift запрашивает у Meta app access token с вашими ID и секретом: при совпадении ключ помечается проверенным, при отказе показывается ошибка Meta. Проверяется только пара ID и секрета — redirect URI, config_id и разрешения проверяются при первом реальном входе. Секрет хранится зашифрованным и целиком не возвращается; если при редактировании оставить поле пустым, сохранится старый.

4. 4

   Скопируйте адреса вебхука и callback

   После сохранения в карточке появятся Webhook URL, Webhook verify token, Deauthorize callback и Data deletion callback. Ваше приложение получает собственный адрес вебхука, и входящие события проверяются вашим App Secret. Пару вебхука вставьте в настройки Webhooks, deauthorize — в настройки Facebook Login, data deletion — в поле в App settings → Basic.

5. 5

   Подключите аккаунт и синхронизируйте Pages

   В разделе «Ulanishlar» (подключения) нажмите «Ulash» (подключить) на карточке Facebook, затем «Page'larni sinxronlash» (синхронизировать Pages) — добавятся Pages и привязанные к ним Instagram-аккаунты. Подпишите каждую Page на вебхуки в Playground (раздел «Page'lar va webhook») или в SDK через fb.subscribe_page.

Какие разрешения нужны приложению?

Это стандартный список «Scope'lar» в Socialift. При использовании config_id те же разрешения выбираются внутри конфигурации.

Ключи в Python SDK

Facebook.from_env() читает из окружения FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, FACEBOOK_CONFIG_ID и META_GRAPH_VERSION.

import asyncio
import secrets

from socialift import Facebook

REDIRECT_URI = "https://example.com/auth/facebook/callback"  # как в Valid OAuth Redirect URIs


async def main() -> None:
    # FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, FACEBOOK_CONFIG_ID, SOCIALIFT_LICENSE_KEY
    async with Facebook.from_env() as fb:
        state = secrets.token_urlsafe(32)  # сохраните в сессии и сверьте в callback
        print(fb.login_url(redirect_uri=REDIRECT_URI, state=state))

        code = input("code: ")
        token = await fb.exchange_code(code, redirect_uri=REDIRECT_URI)
        print(await fb.granted_scopes(token.access_token))  # реально выданные разрешения
        for page in await fb.pages(token.access_token):
            await fb.subscribe_page(page.id, page.access_token, fields=["leadgen", "feed"])


asyncio.run(main())

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

• ▸Redirect URI отличается от указанного в Valid OAuth Redirect URIs (http/https, / в конце, лишний query-параметр).
• ▸В карточку Meta вписаны Instagram app ID/secret (или наоборот) — это разные ключи.
• ▸В конфигурации выбран System user access token — поток входа Socialift ожидает User access token.
• ▸Заполнен Configuration ID, а разрешения меняют в поле «Scope'lar» — в этом случае их меняют в самой конфигурации.
• ▸Вебхук настроен на уровне приложения, но Page не подписана через subscribed_apps — событий не будет.
• ▸До App Review тестируют аккаунтом без роли в приложении — разрешения не выдаются.
• ▸Запрошен Advanced Access для неиспользуемых разрешений — App Review отклонит.
• ▸App Secret лежит во фронтенде или в репозитории.