Основы Meta Graph API
Все интеграции с Instagram и Facebook строятся поверх Meta Graph API. Чтобы в нём разобраться, достаточно четырёх понятий: типы токенов, подпись appsecret_proof, разрешения и лимиты. У Instagram при этом два варианта: Facebook Login (токен страницы) и Instagram Login (без страницы, токен Instagram User) — от выбора зависит модель токенов.
Опубликовано: Обновлено:
Четыре ключевых понятия
- Пользовательский токен
- Действует от имени человека. По нему получают список его страниц. Короткоживущий токен меняется на долгоживущий.
- Токен страницы
- Действует от имени конкретной страницы. В варианте Facebook Login этим токеном работают посты и комментарии страницы, а также Direct, публикации и комментарии привязанного Instagram-аккаунта. В варианте Instagram Login страница не нужна — используется токен Instagram User.
- appsecret_proof
- HMAC-SHA256 от access token'а на секрете приложения. Если включён «Require App Secret», запрос без неё отклоняется. Защита: украденный токен без app secret бесполезен.
- Разрешение (permission)
- Для каждого действия нужно своё разрешение: pages_show_list, pages_read_engagement, instagram_manage_messages (в Instagram Login — instagram_business_manage_messages), leads_retrieval и другие.
Зачем нужен App Review
При Standard Access разрешения работают только для людей с ролью в приложении (админы, разработчики, тестировщики). Для остальных пользователей каждому разрешению нужен Advanced Access — его дают после App Review и проверки компании (Business Verification). Это самый долгий этап.
Практический совет: запрашивайте только действительно необходимые разрешения. Каждое лишнее удлиняет проверку и повышает шанс отказа.
Второй совет: подготовьте понятный воспроизводимый сценарий — команда Meta должна своими глазами увидеть, как используется разрешение.
Лимиты и работа с ними
Graph API ограничивает запросы: на уровне приложения — 200 × число пользователей в час, для Pages, Instagram и Marketing API — лимиты Business Use Case. Расход приходит в заголовках X-App-Usage и X-Business-Use-Case-Usage; при достижении лимита возвращаются ошибки с кодами 4, 17, 32, 613 или 800xx.
Правильное поведение — повтор с экспоненциальной задержкой, ограничение параллельных запросов и кэширование. SDK повторяет запросы с backoff (RetryPolicy) и выбрасывает RateLimitError на кодах 4/17/32/613; retry_after заполняется только из заголовка Retry-After. Время ожидания Meta сообщает в estimated_time_to_regain_access заголовка X-Business-Use-Case-Usage.
Проверьте до начала интеграции
- Аккаунт Instagram профессиональный (Business или Creator); для Facebook Login — привязан к странице Facebook (для Instagram Login страница не нужна).
- Секрет приложения хранится безопасно, appsecret_proof добавляется.
- Список нужных разрешений составлен по минимуму.
- Есть механизм отслеживания срока действия токена.
- Продуманы backoff и очередь на случай лимитов.
- Версия Graph API явно указана в запросах, и её срок отслеживается.
Частые вопросы
Graph API и Instagram API — это разные вещи?
Не совсем. Instagram API — часть платформы Meta и настраивается в приложении Meta, но у него два варианта: Facebook Login (токен страницы, нужна страница) и Instagram Login (токен Instagram User, без страницы). Модель токенов зависит от варианта.
Обязателен ли appsecret_proof?
Зависит от настроек приложения, но для продакшена правильно добавлять его всегда. SDK делает это автоматически.
Нужно ли пользователю входить заново, когда токен истёк?
Истёкший токен продлить нельзя — да. Поэтому обновляйте заранее: токен Instagram Login (60 дней) можно обновить, когда ему не меньше 24 часов (ig.refresh_token); у токенов страниц, полученных из долгоживущего пользовательского токена, нет срока действия. Состояние «переподключить» всё равно нужно на случай отзыва доступа.
Как выбрать версию Graph API?
Версия указывается в адресе запроса (например, /v26.0/me). Meta гарантирует работу каждой версии не менее двух лет; вызовы к истёкшей версии перенаправляются на следующую поддерживаемую, поэтому изменившиеся endpoint'ы могут повести себя иначе. В SDK версия задаётся параметром graph_version=.