Instagram Direct API
Instagram Direct API позволяет читать диалоги бизнес-аккаунта и отвечать на них в пределах 24-часового окна. Socialift нормализует эти вызовы и возвращает каждого собеседника с полным профилем — не только ID и username, но имя, число подписчиков и признак подписки на бизнес.
Обновлено:
Что умеет Instagram Direct API
Instagram Messaging API позволяет читать диалоги Direct бизнес-аккаунта и отвечать на них. Он доступен только профессиональным аккаунтам (Business или Creator): для Instagram Login нужно разрешение instagram_business_manage_messages, для Facebook Login — instagram_manage_messages. Диалог начинает только пользователь, а ответы подчиняются 24-часовому окну.
На практике можно построить инбокс внутри своей системы: список диалогов, последние сообщения, ответы и распределение между операторами. Ограничения: по каждому диалогу доступны только 20 последних сообщений, диалоги из папки «Запросы», неактивные 30 дней, не возвращаются, групповые чаты не поддерживаются — полную историю сохраняйте в своей базе через вебхуки.
Ограничение понятное: отвечать можно в течение 24 часов после последнего сообщения пользователя. После закрытия окна можно отправить только ответ живого оператора с тегом HUMAN_AGENT — до 7 дней, при наличии функции Human Agent, прошедшей App Review. send_message в SDK тег не ставит, поэтому вне окна Meta его отклонит.
Что добавляет Socialift
Полный профиль контакта
Conversations API отдаёт об участнике только ID и username. Socialift добавляет через User Profile API имя, follower_count, is_user_follow_business и is_business_follow_user (профиль доступен после того, как пользователь вам написал).
Параллельные запросы
Запросы профилей идут параллельно (до 8 одновременно) — не нужно ждать 50 последовательных запросов ради 50 диалогов. SDK не кэширует профили: при необходимости храните их в своей базе.
Единая модель ошибок
AuthError и RateLimitError одинаковы для Instagram, Facebook, LinkedIn, TikTok и Telegram. Значение retry_after берётся из ответа.
appsecret_proof
Если передан app_secret, appsecret_proof добавляется к каждому запросу автоматически — при включённом «Require App Secret» Meta без него отклоняет запрос.
Чтение диалогов
import asyncio, os
from socialift import Instagram
async def main(page_token: str):
# Вариант Facebook Login; для Instagram Login: Instagram.from_env() и IG-токен, page_id не нужен
async with Instagram.via_facebook(app_secret=os.environ["FACEBOOK_APP_SECRET"]) as ig:
chats = await ig.conversations(page_token, page_id="1111", ig_user_id="2222")
for chat in chats["data"]:
c = chat["contact"]
if c:
print(c.get("name"), c.get("follower_count"), "подписан:", c.get("is_user_follow_business"))
asyncio.run(main("PAGE_TOKEN"))Отправка сообщения и обработка ошибок
Лимит запросов, закрытое 24-часовое окно и отозванный токен — самые частые состояния в проде.
import asyncio, os
from socialift import AuthError, Instagram, PermissionError, RateLimitError
async def reply(recipient_id: str, page_token: str, text: str):
async with Instagram.via_facebook(app_secret=os.environ["FACEBOOK_APP_SECRET"]) as ig:
try:
await ig.send_message(recipient_id, page_token, text, page_id="1111")
except RateLimitError as exc:
await asyncio.sleep(exc.retry_after or 60) # затем повторите или поставьте в очередь
except PermissionError:
... # 24-часовое окно закрыто — передайте диалог оператору
except AuthError:
... # токен отозван → отправьте пользователя на повторный вход
asyncio.run(reply("IGSID", "PAGE_TOKEN", "Здравствуйте! Отвечаем на ваш вопрос."))При проектировании интеграции с Direct
- Следите за 24-часовым окном — выносите диалоги без ответа в отдельную очередь.
- Сделайте отправку идемпотентной: при повторном вебхуке второй ответ уходить не должен.
- Помечайте, ответил оператор или бот — это нужно для отчётности.
- Храните профиль собеседника в своей базе, но периодически обновляйте число подписчиков.
- Показывайте в интерфейсе состояние, когда пользователь заблокировал вас или отозвал доступ.
Частые вопросы
Можно ли автоматически отвечать в Instagram Direct через API?
Да, в течение 24 часов после последнего сообщения пользователя. Вне окна автоматические сообщения запрещены: только живой оператор может ответить с тегом HUMAN_AGENT до 7 дней (функция Human Agent требует App Review). send_message в Socialift отправляет только текст и не ставит тегов.
Какие разрешения нужны для Direct API?
Для Instagram Login — instagram_business_basic и instagram_business_manage_messages; для Facebook Login — instagram_basic, instagram_manage_messages и pages_show_list (в этом варианте аккаунт привязан к странице Facebook). Для чужих аккаунтов нужен Advanced Access через App Review.
Какие данные о собеседнике можно получить?
Через Socialift приходят имя, username, число подписчиков, is_user_follow_business и is_business_follow_user. Meta отдаёт профиль, только если пользователь написал вам или нажал icebreaker; профиль заблокировавшего вас пользователя недоступен. Эти поля используют для квалификации лида.
Можно ли первым написать пользователю в Instagram Direct?
Нет. Диалог начинается только тогда, когда пользователь пишет бизнес-аккаунту — в Direct, через пост, упоминание в истории или другой канал. Групповые чаты не поддерживаются: в одном диалоге профессиональный аккаунт общается только с одним клиентом.
Работают ли SDK-методы Direct в бесплатный месяц?
Да. Первые 30 дней токен открывает все возможности SDK, включая conversations, messages, send_message и contact. Дальше токен продлевается 30-дневными периодами с баланса, и возможности зависят от плана токена — точный список показывает «Tekshirish va muhitlar» (проверка и окружения) в кабинете. Playground в кабинете работает при любом плане.
Источники
Связанные страницы
Заберите Direct в свою систему
Получите токен и вытяните первый список диалогов через SDK уже сегодня.
Получить бесплатный токен →