Будь-яка зовнішня аналітика Instagram — свій дашборд, скрипт, готовий self-hosted продукт — починається з одного й того самого: access token до Instagram Graph API. Процес його отримання нескладний, але інтерфейс Meta for Developers заплутаний, термінологія змінюється щороку, а половина інструкцій в інтернеті описує старий застарілий Basic Display API. Нижче — актуальний покроковий шлях до робочого токена зі статистикою, плюс розбір типових помилок.
Що дає Graph API і чого не дає
Instagram Graph API — єдиний легальний спосіб отримати внутрішню статистику акаунта програмно: охоплення, покази, збереження, поширення, приріст підписників, демографію аудиторії. Це ті самі дані, що у вбудованій статистиці застосунку, але через API їх можна забирати щодня, накопичувати і будувати власні звіти.
Важливі межі: API віддає статистику лише вашого акаунта (або акаунтів, до яких вам надали доступ) — «подивитись метрики конкурента» через нього не можна. І працює він тільки з професійними акаунтами.
Крок 1: переведіть акаунт у Business або Creator
Особисті акаунти статистику через API не віддають — це обмеження Meta. Перемкнутися: Instagram → Налаштування → Тип акаунта та інструменти → Перейти на професійний акаунт. Це безкоштовно і займає дві хвилини. Для бізнесу обирайте Business, для авторів — Creator: для статистики через API підходять обидва.
Рекомендація з практики: прив'яжіть Instagram до Facebook-сторінки. Для частини сценаріїв доступу це обов'язково, і навіть там, де ні, — зв'язка робить поведінку API передбачуванішою.
Крок 2: створіть застосунок у Meta for Developers
- Зайдіть на developers.facebook.com під своїм акаунтом Facebook.
- My Apps → Create App.
- На кроці вибору use case оберіть «Manage messaging & content on Instagram» — саме цей варіант відкриває доступ до Instagram API для роботи з контентом і статистикою. Не обирайте «Other»/«None»: потім доведеться діставати потрібні продукти вручну.
- Заповніть назву застосунку і контактний email, створіть застосунок.
«Застосунок» тут — просто контейнер для прав доступу і токенів. Публікувати його в App Review для особистого використання не потрібно: у режимі розробки він повноцінно працює з акаунтами, що мають до нього роль.
Крок 3: додайте permission instagram_business_manage_insights
Дозволи (permissions) визначають, що саме зможе токен. Для статистики ключовий — instagram_business_manage_insights: він відкриває ендпоінти insights по акаунту і по окремих публікаціях (охоплення, saves, shares, демографія, приріст підписників).
У налаштуваннях застосунку відкрийте розділ Instagram → API setup, підключіть свій Instagram-акаунт до застосунку і переконайтеся, що в списку дозволів при генерації токена відмічений instagram_business_manage_insights. Якщо плануєте надалі ще й публікувати через API — додайте відповідні content-дозволи, але для аналітики достатньо insights.
Крок 4: згенеруйте access token
У тому ж розділі Instagram → API setup є кнопка генерації токена для підключеного акаунта. Натискаєте, підтверджуєте дозволи у вікні Instagram — отримуєте довгий рядок виду IGAA.... Це і є access token.
Що треба знати про життя токенів:
| Тип токена | Термін життя | Особливість |
|---|---|---|
| Короткоживучий | ~1 година | Видається за замовчуванням у частині флоу |
| Довгоживучий | ~60 днів | Отримується обміном короткоживучого або одразу в API setup |
| Оновлений довгоживучий | +60 днів | Оновлюється запитом до refresh_access_token |
Практичний висновок: одразу беріть довгоживучий токен і поставте нагадування (або автоматику) на оновлення раз на 1,5–2 місяці. «Дашборд раптом перестав оновлюватись» у 9 з 10 випадків означає протухлий токен.
Крок 5: перевірте токен одним запитом
Перш ніж вставляти токен кудись, перевірте його в терміналі:
curl "https://graph.instagram.com/me?fields=id,username&access_token=ВАШ_ТОКЕН"
Якщо у відповідь прийшов ваш username — токен живий. Далі перевірте insights:
curl "https://graph.instagram.com/me/insights?metric=reach&period=day&access_token=ВАШ_ТОКЕН"
Цифри у відповіді означають, що permission на статистику працює і можна підключати аналітику.
Типові помилки і як їх лікувати
| Симптом | Причина | Рішення |
|---|---|---|
| (#10) Permission denied на insights | Немає instagram_business_manage_insights |
Перегенеруйте токен із цим дозволом |
| Invalid OAuth access token | Токен протух або скопійований з пробілом | Згенеруйте новий, копіюйте повністю |
| Порожня демографія | Менше ~100 підписників | Обмеження Meta, чекати росту акаунта |
| API не бачить акаунт | Акаунт особистий, не Business/Creator | Перемкнути тип акаунта (крок 1) |
| Метрика повертає помилку | Метрика недоступна для цього типу медіа чи періоду | Звірити список метрик для media type у документації |
| Все працювало і зламалось через 2 міс | Закінчився довгоживучий токен | Оновлення через refresh_access_token, поставити автоматику |
Куди вставити токен: готовий дашборд замість самописних скриптів
Токен сам по собі — лише перепустка. Щоб отримати з нього користь, потрібна система, яка щодня забирає метрики, накопичує історію і малює звіти. Якщо не хочете писати її самостійно, є безкоштовний open-source Instagram Dashboard від MaxICo Labs: self-hosted, розгортається через Docker за 10 хвилин, а токен вставляється прямо в інтерфейсі — заходите в ⚙ Settings, вставляєте рядок IGAA..., і дашборд починає збирати KPI, ER% по публікаціях, ріст підписників із маркерами Reels і демографію. Жодного редагування конфігів на сервері; всі API-роути закриті авторизацією, токен зберігається лише у вашому сховищі. Подивитись живе демо: inst-dashbord.maxicolabs.com.
Що робити агенції з кількома клієнтами
Якщо ви ведете кілька акаунтів, не намагайтеся обслужити всіх одним токеном — у кожного клієнтського акаунта свій токен зі своїми правами. Робочий процес: клієнт додає ваш акаунт у свій Meta-застосунок (або ви створюєте застосунок і даєте клієнту роль), генеруєте окремий токен на акаунт і зберігаєте їх ізольовано. Так відкликання одного токена не зачіпає решту клієнтів, а в разі завершення співпраці доступ закривається одним кліком.
Безпека токена: три правила
Access token із permission на insights — це повний доступ до статистики вашого акаунта. Поводитися з ним треба як із паролем:
- Ніколи не комітьте токен у git. Класична помилка: токен у конфігу, конфіг у публічному репозиторії, через годину його вже знайшли сканери. Тримайте токен у
.env, а.env— у.gitignore. У готових продуктах на кшталт Instagram Dashboard це зроблено за замовчуванням: секрети не потрапляють у репозиторій структурно. - Не вставляйте токен у сторонні «безкоштовні чекери». Сайти формату «перевір свій токен онлайн» — найпростіший спосіб його злити. Перевіряйте через curl зі свого термінала або через офіційний Access Token Debugger у Meta for Developers.
- Токен скомпрометований — відкликайте одразу. У налаштуваннях застосунку можна інвалідувати токени і згенерувати нові. Якщо токен світився у скріншоті, логах CI або публічному репозиторії — вважайте його злитим і міняйте, навіть «про всяк випадок».
І окремо про зберігання: якщо ваш дашборд self-hosted, токен лежить на вашому сервері і нікуди не передається. Якщо ж ви віддаєте токен SaaS-сервісу — ви фактично довіряєте статистику свого акаунта чужій інфраструктурі. Це нормальний компроміс, але він має бути усвідомленим.
Підсумок
Весь шлях — Business-акаунт → застосунок у Meta for Developers → use case «Manage messaging & content on Instagram» → permission instagram_business_manage_insights → довгоживучий токен → перевірка через curl — займає 10–15 хвилин, якщо йти по кроках і не плутати сучасний Instagram API зі старим Basic Display. Найчастіша причина проблем — не помилки в коді, а протухлі токени і відсутній permission.
Далі токен можна віддати безкоштовному Instagram Dashboard і отримати повну аналітику без рядка коду. А якщо вашому бізнесу потрібно більше — інтеграція Instagram-даних у власну звітність, наскрізна аналітика чи інші AI-рішення для бізнесу — команда MaxICo Labs допоможе. Почніть із безкоштовного 30-хвилинного AI-аудиту: maxicolabs.com/contact.