Instagram Messaging API: технический разбор API для директа
Instagram Messaging API позволяет профессиональному аккаунту получать сообщения Direct через вебхуки и отвечать через POST /<IG_ID>/messages. Первым пишет клиент; после этого на ответ есть 24 часа, а живой оператор может ответить в течение 7 дней с тегом HUMAN_AGENT, который требует App Review. Для Instagram Login нужно instagram_business_manage_messages, Facebook Login работает через Messenger Platform.
Обновлено:
Как работает API для директа Instagram?
Диалог всегда начинает пользователь Instagram — из профиля, поста, упоминания в истории или другой точки входа. Meta присылает вебхук messages с Instagram-scoped ID отправителя (IGSID). Ваш сервер отвечает на этот IGSID через Send API в течение 24 часов. Историю отдаёт Conversations API, данные профиля — User Profile API, но только после того, как пользователь вам написал.
Эта статья — про механику API. Что допустимо с точки зрения бизнеса и продаж, разобрано в статье об автоматизации Instagram Direct, а что Socialift добавляет поверх «сырых» эндпоинтов — на странице Instagram Direct API.
Требования в зависимости от способа входа
| Instagram Login | Facebook Login (Messenger Platform) | |
|---|---|---|
| Хост | graph.instagram.com | graph.facebook.com |
| Токен | Instagram User access token | Токен страницы (от человека с задачей MESSAGE) |
| Разрешения | instagram_business_basic, instagram_business_manage_messages | instagram_basic, instagram_manage_messages, pages_manage_metadata |
| Отправка | POST /<IG_ID>/messages | POST /<PAGE_ID>/messages |
| Список диалогов | GET /me/conversations | GET /<PAGE_ID>/conversations?platform=instagram |
| Подписка на вебхуки | POST /me/subscribed_apps | Объект instagram в App Dashboard + подписка привязанной страницы |
| При Standard Access | Только аккаунты, которыми вы управляете | Сообщения только людям с ролью в приложении |
Примечания и ограничения
Для пути через Facebook Login Meta также требует включить в приложении Instagram переключатель «Разрешить доступ к сообщениям» (Настройки → Сообщения и ответы на истории → Управление сообщениями → Подключённые инструменты).
Окно 24 часа и тег HUMAN_AGENT
Приложение может написать пользователю Instagram только после того, как он сам написал профессиональному аккаунту. С момента последнего сообщения пользователя у вас 24 часа на ответ, и внутри этого окна ответ может содержать рекламный контент.
Если сотруднику нужно больше времени — бизнес не работает в выходные или вопрос решается дольше суток, — ответ можно отправить с тегом сообщения HUMAN_AGENT в течение 7 дней после сообщения пользователя. Тег предназначен для ручных ответов живого оператора; функция Human Agent требует App Review и проверки компании.
За пределами этих окон достучаться до пользователя через API нельзя: One-Time Notification, News Messaging и Sponsored Messages из Messenger для Instagram Messaging API недоступны.
В Socialift SDK send_message отправляет обычный текстовый ответ без тегов. Если окно закрыто, Meta отклоняет вызов, а SDK выбрасывает PermissionError — перехватите его и передайте диалог человеку вместо повторных попыток.
Поля вебхуков для сообщений Instagram
Подписывайтесь только на поля, которые обрабатываете. В Instagram Login им нужны instagram_business_basic и instagram_business_manage_messages, а приложение должно быть в режиме Live.
| Поле | Когда приходит |
|---|---|
| messages | Пользователь отправил сообщение; в payload — sender.id (IGSID), recipient.id, timestamp, message.mid и текст или вложения |
| message_echoes | Сообщение отправил бизнес-аккаунт (поле Instagram Login); на пути Messenger Platform такие сообщения приходят в messages с is_echo |
| message_reactions | Пользователь поставил реакцию на сообщение |
| messaging_postbacks | Пользователь нажал icebreaker или кнопку |
| messaging_seen | Пользователь прочитал сообщение |
| messaging_referral | Пользователь открыл диалог по ссылке ig.me |
| message_edit | Пользователь отредактировал сообщение (с 10 сентября 2025 года) |
Приём сообщений: обработчик вебхука
Хелперы вебхуков Socialift проверяют X-Hub-Signature-256, приводят оба формата payload к одному виду и строят стабильный ключ дедупликации.
import json, os
from socialift.webhooks import dedupe_key, parse_events, verify_request
APP_SECRET = os.environ["WEBHOOK_APP_SECRET"] # секрет приложения, принимающего вебхук
def handle_instagram_webhook(raw_body: bytes, headers, seen: set) -> int:
if not verify_request(APP_SECRET, raw_body, headers):
return 403
for event in parse_events(json.loads(raw_body)):
key = dedupe_key(event)
if event.field != "messages" or key in seen:
continue
seen.add(key)
message = event.value.get("message") or {}
if message.get("is_echo"):
continue # наше собственное исходящее сообщение
igsid = event.value["sender"]["id"]
print("DM:", igsid, message.get("text")) # в очередь, не обрабатывать здесь
return 200Возвращайте 200 быстро, а обработку уносите в очередь: документация Messenger Platform ждёт 200 OK в течение 5 секунд и отключает вебхук, который не доставляется на протяжении часа.
seen здесь заменяет уникальный столбец в вашей базе: Meta может доставить одно событие несколько раз.
Чтение диалогов и ответ через SDK
import asyncio, os
from socialift import Instagram, PermissionError as MetaPermissionError
async def main():
token = os.environ["IG_USER_TOKEN"]
async with Instagram.from_env() as ig:
chats = await ig.conversations(token, limit=10)
for chat in chats["data"]:
contact = chat["contact"] or {}
history = await ig.messages(chat["id"], token, limit=20)
print(contact.get("username"), len(history["data"]))
igsid = os.environ["CUSTOMER_IGSID"]
print(await ig.contact(igsid, token))
try:
await ig.send_message(igsid, token, "Спасибо! Менеджер скоро ответит.")
except MetaPermissionError:
print("Окно 24 часа закрыто: передайте диалог оператору")
asyncio.run(main())conversations возвращает data (у каждого элемента есть id и contact) и paging; для следующей страницы передайте after=. При enrich=True (по умолчанию) профили собеседников запрашиваются параллельно.
contact(igsid, token) вызывает User Profile API и, если профиль недоступен, возвращает available: False вместо исключения.
Facebook Login: Instagram.via_facebook(app_secret=...), затем ig.conversations(page_token, page_id=..., ig_user_id=...) и ig.send_message(igsid, page_token, text, page_id=...) — параметр platform=instagram SDK добавляет сам.
send_message покрывает текст; вложения, quick replies, шаблоны, теги сообщений и private replies вызываются напрямую через Graph API.
Private replies: ответ в директ на комментарий
Private reply отправляет сообщение в Direct человеку, оставившему комментарий под постом, Reels, историей, прямым эфиром или рекламным постом аккаунта. Вызов тот же — POST /<IG_ID>/messages, но в recipient вместо IGSID передаётся comment_id.
Правила: ответить нужно в течение 7 дней после комментария (для Live — только пока идёт эфир); на один комментарий — только одно сообщение; следующие сообщения возможны, только если пользователь ответит, и в течение 24 часов. Сообщение попадает во «Входящие» или в «Запросы» в зависимости от того, подписан ли пользователь на аккаунт.
Разрешения отличаются от обычной переписки: в Instagram Login — instagram_business_basic и instagram_business_manage_comments; в Facebook Login — instagram_basic, instagram_manage_comments и pages_read_engagement. Лимит — 750 вызовов в час для постов и Reels и 100 в секунду для комментариев в эфире.
Лимиты отправки сообщений в Instagram
| Что | Лимит |
|---|---|
| Conversations API | 2 вызова в секунду на профессиональный аккаунт |
| Send API: текст, ссылки, реакции, стикеры | 100 вызовов в секунду на аккаунт |
| Send API: аудио и видео | 10 вызовов в секунду на аккаунт |
| Текст сообщения | UTF-8, до 1000 байт |
| Изображений в одном сообщении | До 10 |
| Размер вложений | Изображения 8 МБ; аудио, видео и PDF 25 МБ |
| Детали сообщений через Conversations API | Только 20 последних сообщений диалога |
| Папка «Запросы» | Диалоги без активности 30 дней не возвращаются |
Ограничения, которые нужно заложить в архитектуру
- Нельзя написать первым: пользователь должен начать диалог сам.
- Групповых чатов нет — один клиент на диалог.
- Папками входящих (Primary, General, Requests) через API управлять нельзя.
- Доступны детали только 20 последних сообщений — сохраняйте входящие из вебхуков у себя.
- Данные User Profile API (name, username, profile_pic, follower_count, is_user_follow_business, is_business_follow_user, is_verified_user) открываются только после сообщения пользователя или нажатия icebreaker; ссылка profile_pic истекает через несколько дней.
- Если пользователь заблокировал бизнес, его профиль прочитать нельзя.
- Медиа и посты, которыми вы делитесь в сообщениях, должны принадлежать бизнес-аккаунту.
- Вебхуки приходят, только если приложение в режиме Live.
Частые вопросы
Можно ли через Instagram API написать пользователю первым?
Нет. Диалог начинается только тогда, когда пользователь Instagram пишет профессиональному аккаунту (для private replies — оставляет комментарий к его контенту). Холодные и массовые рассылки через Instagram Messaging API невозможны.
Что происходит после закрытия 24-часового окна?
Обычные ответы отклоняются. Живой оператор может ответить в течение 7 дней после последнего сообщения пользователя с тегом HUMAN_AGENT — для этого функция Human Agent должна пройти App Review. Автоматические сообщения под этот тег не подходят.
Какие лимиты у API для директа Instagram?
Send API разрешает 100 вызовов в секунду на аккаунт для текста, ссылок, реакций и стикеров и 10 в секунду для аудио и видео. Conversations API — 2 вызова в секунду, private replies — 750 в час для постов и Reels.
Нужна ли страница Facebook для Instagram Messaging API?
Нет. С Instagram Login вы обращаетесь к graph.instagram.com с разрешением instagram_business_manage_messages. Страница нужна только на пути Facebook Login, где сообщения Instagram идут через Messenger Platform с токеном страницы.
Почему не удаётся получить профиль клиента?
User Profile API отдаёт данные только после того, как пользователь написал аккаунту, нажал icebreaker или постоянное меню. Если он только оставил комментарий или заблокировал вас, Meta вернёт ошибку — метод contact в Socialift SDK в этом случае вернёт available: False.