Instagram API на Python и Node.js: рабочие примеры
Instagram API не требует ничего, кроме HTTPS, поэтому пакет requests в Python и встроенный fetch в Node.js справляются с ним: POST /<IG_ID>/media и media_publish публикуют материал, /<IG_MEDIA_ID>/comments и /<IG_COMMENT_ID>/replies читают комментарии и отвечают на них, /insights возвращает метрики, а вебхук проверяется HMAC-SHA256 от сырого тела запроса. Каждая ошибка содержит код и подкод, по которым видно, поможет ли повторная попытка.
easyCoexistence выполняет те же задачи как инструменты MCP для Claude, ChatGPT или вашего агента, а токен остаётся на её стороне: publish_instagram_post, reply_to_comment, get_social_insights и set_social_webhook_destination, через официальный API Meta.
Последняя версия Graph API, представленная 29 июля 2026 г.; v25.0 остаётся доступной до 29 июля 2028 г.
Как часто Meta советует проверять status_code видеоконтейнера, но не более 5 минут.
Наибольшее число комментариев, которое возвращает один запрос GET /<IG_MEDIA_ID>/comments; ответы приходят только при раскрытии полей.
Временная ошибка публикации, при которой Meta советует повторить попытку 1–2 раза в течение от 30 секунд до 2 минут.
Префикс в X-Hub-Signature-256, перед HMAC-SHA256 тела запроса, подписанного секретом приложения.
Что нужно для примеров?
Среда выполнения, токен и четыре значения. Примеры обращаются к Instagram API через Instagram Login на graph.instagram.com. Приложение с Unified Login использует те же пути с ID аккаунта, на узле Graph из Facebook Login и с токеном системного пользователя Business Integration. Для Python нужен пакет requests, а для вебхука ещё Flask. Node.js нужна версия 18 или новее, чтобы использовать встроенный fetch.
- GRAPH: https://graph.instagram.com/v26.0, узел и версия API.
IG_ID: ID профессионального аккаунта,user_id, который возвращает GET /me.- TOKEN: долгоживущий токен доступа Instagram User, хранящийся на сервере.
APP_SECRETиVERIFY_TOKEN: для проверки запросов вебхука.
Как вызывать API и обрабатывать ошибки в Python?
Через одну вспомогательную функцию, общую для примеров на Python ниже. Она передаёт токен как access_token, вызывает MetaError с кодом Meta, подкодом и fbtrace_id и повторяет только то, что Meta называет временным: коды 1 и 2, коды ограничения частоты 4, 17 и 80002, а также подкоды 2207001, 2207003, 2207008 и 2207032. Код 4 с подкодом 2207051 означает подозрение на спам, поэтому выполнение сразу останавливается.
import json
import time
import requests
GRAPH = "https://graph.instagram.com/v26.0"
IG_ID = "<IG_ID>" # user_id from GET /me
TOKEN = "<TOKEN>" # long-lived Instagram User access token, server side only
RETRY_CODES = {1, 2, 4, 17, 80002}
RETRY_SUBCODES = {2207001, 2207003, 2207008, 2207032}
class MetaError(Exception):
def __init__(self, error: dict, status: int):
super().__init__(error.get("message", f"HTTP {status}"))
self.code = error.get("code")
self.subcode = error.get("error_subcode")
self.fbtrace_id = error.get("fbtrace_id") # log it: Meta support asks for it
@property
def needs_new_token(self) -> bool:
return self.code in (102, 190)
@property
def retryable(self) -> bool:
if self.subcode == 2207051: # code 4 with this subcode is suspected spam: stop
return False
return self.code in RETRY_CODES or self.subcode in RETRY_SUBCODES
def wait_seconds(resp) -> int:
"""estimated_time_to_regain_access from X-Business-Use-Case-Usage, at least 60 s."""
try:
usage = json.loads(resp.headers.get("X-Business-Use-Case-Usage", "{}"))
minutes = max(e.get("estimated_time_to_regain_access", 0) for v in usage.values() for e in v)
except (ValueError, AttributeError, TypeError):
minutes = 0
return max(60, int(minutes) * 60)
def graph(method: str, path: str, attempts: int = 3, **params) -> dict:
if attempts < 1:
raise ValueError("attempts must be at least 1")
params["access_token"] = TOKEN
for attempt in range(1, attempts + 1):
resp = requests.request(method, f"{GRAPH}/{path}", params=params, timeout=30)
try:
data = resp.json()
except ValueError:
data = {}
if resp.ok and "error" not in data:
return data
err = MetaError(data.get("error", {}), resp.status_code)
if not err.retryable or attempt == attempts:
raise err
time.sleep(wait_seconds(resp))Как вызывать API и обрабатывать ошибки в Node.js?
С помощью той же вспомогательной функции для Node.js 18 или новее: она использует fetch и не требует зависимостей. Вызов при ограничении частоты ждёт estimated_time_to_regain_access, то есть минуты, которые Meta указывает в заголовке X-Business-Use-Case-Usage, или 60 секунд, если заголовка нет, поскольку Meta учитывает вызовы, сделанные во время ограничения. needsNewToken отмечает коды 190 и 102, которые не исправит никакая повторная попытка.
const GRAPH = "https://graph.instagram.com/v26.0";
const IG_ID = process.env.IG_ID; // user_id from GET /me
const TOKEN = process.env.TOKEN; // long-lived Instagram User access token, server side only
const RETRY_CODES = new Set([1, 2, 4, 17, 80002]);
const RETRY_SUBCODES = new Set([2207001, 2207003, 2207008, 2207032]);
export class MetaError extends Error {
constructor(error, status) {
super(error.message ?? `HTTP ${status}`);
this.code = error.code;
this.subcode = error.error_subcode;
this.fbtraceId = error.fbtrace_id; // log it: Meta support asks for it
}
get needsNewToken() {
return this.code === 190 || this.code === 102;
}
get retryable() {
if (this.subcode === 2207051) return false; // code 4 with this subcode is suspected spam: stop
return RETRY_CODES.has(this.code) || RETRY_SUBCODES.has(this.subcode);
}
}
export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// estimated_time_to_regain_access from X-Business-Use-Case-Usage, at least 60 s
function waitMs(res) {
try {
const usage = JSON.parse(res.headers.get("x-business-use-case-usage") ?? "{}");
const minutes = Math.max(0, ...Object.values(usage).flat().map((e) => e.estimated_time_to_regain_access ?? 0));
return Math.max(60, minutes * 60) * 1000;
} catch {
return 60_000;
}
}
export async function graph(method, path, params = {}, attempts = 3) {
const url = new URL(`${GRAPH}/${path}`);
for (const [key, value] of Object.entries({ ...params, access_token: TOKEN })) {
url.searchParams.set(key, String(value));
}
for (let attempt = 1; attempt <= attempts; attempt++) {
const res = await fetch(url, { method });
const data = await res.json().catch(() => ({}));
if (res.ok && !data.error) return data;
const err = new MetaError(data.error ?? {}, res.status);
if (!err.retryable || attempt === attempts) throw err;
await sleep(waitMs(res));
}
throw new Error("attempts must be at least 1");
}Как опубликовать фото и Reel в Python?
Оба случая следуют потоку контейнеров. Контейнер фото готов сразу, поэтому media_publish вызывается сразу после него. Видео Reel сначала обрабатывается: функция проверяет status_code раз в минуту в течение до 5 минут, как советует Meta, публикует при FINISHED и останавливается при ERROR или EXPIRED. Изображения должны быть в формате JPEG, а медиафайл должен находиться по публичному URL.
# Uses graph(), IG_ID and time from the helper above
def publish_photo(image_url: str, caption: str) -> str:
"""A JPEG at a public URL: create the container, then publish it."""
container = graph("POST", f"{IG_ID}/media", image_url=image_url, caption=caption)
return graph("POST", f"{IG_ID}/media_publish", creation_id=container["id"])["id"]
def publish_reel(video_url: str, caption: str) -> str:
"""A Reel: publish once Meta has processed the video, checking once a minute."""
cid = graph("POST", f"{IG_ID}/media", media_type="REELS", video_url=video_url, caption=caption)["id"]
for _ in range(5): # Meta: once a minute, for no more than 5 minutes
time.sleep(60)
status = graph("GET", cid, fields="status_code")["status_code"]
if status == "FINISHED":
return graph("POST", f"{IG_ID}/media_publish", creation_id=cid)["id"]
if status in ("ERROR", "EXPIRED"):
raise RuntimeError(f"Container {cid} ended as {status}")
raise TimeoutError(f"Container {cid} is still processing: check it again later")Как опубликовать фото и Reel в Node.js?
Те же две функции, каждая возвращает ID нового медиа. Контейнер, который всё ещё в статусе IN_PROGRESS после пяти проверок, остаётся действительным до 24 часов после создания, поэтому ошибка советует проверить его позже. Так не нужно создавать второй контейнер, расходуя лимит аккаунта в 400 в день.
// Uses graph(), sleep() and IG_ID from the helper above
export async function publishPhoto(imageUrl, caption) {
const { id } = await graph("POST", `${IG_ID}/media`, { image_url: imageUrl, caption });
return (await graph("POST", `${IG_ID}/media_publish`, { creation_id: id })).id;
}
export async function publishReel(videoUrl, caption) {
const { id } = await graph("POST", `${IG_ID}/media`, { media_type: "REELS", video_url: videoUrl, caption });
for (let check = 0; check < 5; check++) {
await sleep(60_000); // Meta: once a minute, for no more than 5 minutes
const { status_code: status } = await graph("GET", id, { fields: "status_code" });
if (status === "FINISHED") return (await graph("POST", `${IG_ID}/media_publish`, { creation_id: id })).id;
if (status === "ERROR" || status === "EXPIRED") throw new Error(`Container ${id} ended as ${status}`);
}
throw new Error(`Container ${id} is still processing: check it again later`);
}Как читать комментарии и отвечать в Python?
GET /<IG_MEDIA_ID>/comments возвращает комментарии верхнего уровня, сначала новые, до 50 за запрос, а POST /<IG_COMMENT_ID>/replies публикует публичный ответ на один из них. Функция запрашивает у вашей функции обратного вызова текст каждого ответа и пропускает комментарии, для которых он не возвращён. Скрытые комментарии нельзя ответить, а ответ на ответ попадает к комментарию верхнего уровня.
# Uses graph() from the helper above
def reply_to_comments(media_id: str, write_reply) -> int:
"""Reply in public to each comment write_reply returns text for."""
page = graph("GET", f"{media_id}/comments", fields="id,text,username,timestamp")
sent = 0
for comment in page.get("data", []):
text = write_reply(comment)
if text:
graph("POST", f"{comment['id']}/replies", message=text)
sent += 1
return sent
# Example: reply to questions about price
reply_to_comments("<IG_MEDIA_ID>", lambda c: "Prices are in our bio link." if "price" in c["text"].lower() else None)Как читать комментарии и отвечать в Node.js?
Тот же цикл в Node.js. Оба вызова используют instagram_business_basic и instagram_business_manage_comments, а поле username требует второго из них. Чтобы ответить в личных сообщениях, POST /<IG_ID>/messages с recipient.comment_id отправляет комментатору одно личное сообщение в течение 7 дней после комментария, а последующие сообщения ждут, пока он ответит.
// Uses graph() from the helper above
// Reply in public to each comment writeReply returns text for
export async function replyToComments(mediaId, writeReply) {
const { data = [] } = await graph("GET", `${mediaId}/comments`, { fields: "id,text,username,timestamp" });
let sent = 0;
for (const comment of data) {
const text = writeReply(comment);
if (text) {
await graph("POST", `${comment.id}/replies`, { message: text });
sent++;
}
}
return sent;
}
// Example: reply to questions about price
await replyToComments("<IG_MEDIA_ID>", (c) => (/price/i.test(c.text) ? "Prices are in our bio link." : null));Как читать инсайты в Python?
Инсайты аккаунта запрашиваются с period=day и metric_type=total_value, и каждая метрика затем сообщает total_value.value; инсайты публикации возвращают values[0].value. Пример запрашивает для аккаунта reach, views и accounts_engaged, а для публикации или Reel: reach, views, likes, comments, saved и shares, которые справочник Meta перечисляет для обоих случаев. Метрика без данных опускается, а не возвращается как 0.
# Uses graph() and IG_ID from the helper above
def account_insights() -> dict:
"""Reach, views and accounts engaged over the last 24 hours."""
data = graph("GET", f"{IG_ID}/insights", metric="reach,views,accounts_engaged",
period="day", metric_type="total_value")["data"]
return {m["name"]: m["total_value"]["value"] for m in data}
def post_insights(media_id: str) -> dict:
"""Totals for one post or Reel."""
data = graph("GET", f"{media_id}/insights", metric="reach,views,likes,comments,saved,shares")["data"]
return {m["name"]: m["values"][0]["value"] for m in data}Как читать инсайты в Node.js?
Те же два запроса в Node.js, каждый возвращает объект, ключом которого служит название метрики. Ни один не отправляет разбивку (breakdown): Meta предупреждает, что запрос разбивки, которую метрика не поддерживает, завершается ошибкой с текстом unknown error, а данные инсайтов могут отставать до 48 часов, поэтому свежие публикации стоит читать повторно позже.
// Uses graph() and IG_ID from the helper above
// Reach, views and accounts engaged over the last 24 hours
export async function accountInsights() {
const { data } = await graph("GET", `${IG_ID}/insights`, {
metric: "reach,views,accounts_engaged",
period: "day",
metric_type: "total_value",
});
return Object.fromEntries(data.map((m) => [m.name, m.total_value?.value]));
}
// Totals for one post or Reel
export async function postInsights(mediaId) {
const { data } = await graph("GET", `${mediaId}/insights`, { metric: "reach,views,likes,comments,saved,shares" });
return Object.fromEntries(data.map((m) => [m.name, m.values?.[0]?.value]));
}Как проверить вебхук в Python?
С помощью Flask, двумя маршрутами на одном пути. GET отвечает на запрос проверки от Meta: когда hub.mode равен subscribe и hub.verify_token совпадает, он возвращает hub.challenge как обычный текст, а иначе 403. POST вычисляет sha256= плюс HMAC-SHA256 сырого тела запроса с секретом приложения, сравнивает его с X-Hub-Signature-256 за постоянное время и отвечает 200 до начала любой медленной работы.
import hashlib
import hmac
import json
import os
from queue import Queue
from flask import Flask, abort, request
app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()
jobs: Queue = Queue() # swap for your own job queue
@app.get("/webhooks/instagram")
def verify():
"""Meta's verification request: send hub.challenge back when the token matches."""
args = request.args
if args.get("hub.mode") == "subscribe" and args.get("hub.verify_token") == VERIFY_TOKEN:
return args.get("hub.challenge", ""), 200, {"Content-Type": "text/plain"}
abort(403)
@app.post("/webhooks/instagram")
def receive():
"""An event: check X-Hub-Signature-256 over the raw bytes, then answer at once."""
raw = request.get_data()
expected = b"sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest().encode()
if not hmac.compare_digest(expected, request.headers.get("X-Hub-Signature-256", "").encode()):
abort(401)
for entry in json.loads(raw).get("entry", []):
jobs.put(entry) # slow work happens elsewhere; Meta wants a quick 200
return "", 200Как проверить вебхук в Node.js?
С помощью встроенного модуля http, без фреймворка. Тело собирается как сырые байты до того, как что-либо его разбирает, потому что разобранное и заново сериализованное тело больше не совпадает с подписью, которую вычислила Meta. Meta повторяет неудачное уведомление до 36 часов, поэтому обработчик также должен пропускать события, которые уже обработал.
import crypto from "node:crypto";
import http from "node:http";
const { VERIFY_TOKEN, APP_SECRET } = process.env;
const PATH = "/webhooks/instagram";
const jobs = []; // swap for your own job queue
http
.createServer((req, res) => {
const url = new URL(req.url, "http://localhost");
if (url.pathname !== PATH) return res.writeHead(404).end();
if (req.method === "GET") {
// Meta's verification request: send hub.challenge back when the token matches
const ok =
url.searchParams.get("hub.mode") === "subscribe" &&
url.searchParams.get("hub.verify_token") === VERIFY_TOKEN;
return res
.writeHead(ok ? 200 : 403, { "Content-Type": "text/plain" })
.end(ok ? url.searchParams.get("hub.challenge") ?? "" : "");
}
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", () => {
const raw = Buffer.concat(chunks); // the exact bytes Meta signed
const expected = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
const given = Buffer.from(req.headers["x-hub-signature-256"] ?? "");
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.writeHead(401).end();
}
res.writeHead(200).end(); // answer first, work after
try {
for (const entry of JSON.parse(raw.toString("utf8")).entry ?? []) jobs.push(entry);
} catch {
// not JSON: nothing to queue
}
});
})
.listen(3000);Какие ошибки Meta должен повторять код?
Только временные, поскольку остальные возвращают тот же ответ, пока что-то не изменится: файл, URL, разрешение или состояние аккаунта. Справочники ошибок Meta указывают действие для каждого кода, который различают вспомогательные функции выше:
Как запустить тот же код с данными easyCoexistence?
Запустить его на токене easyCoexistence нельзя: токены Instagram никогда не выдаются (условия Meta), поэтому get_social_credentials и GET /api/v1/channels/:id?credentials=1 Partner API возвращают ID аккаунта и базовый адрес API без токена. Вместо этого те же задачи выполняются как инструменты MCP, через Claude, ChatGPT или другой MCP-клиент, а приведённые выше вспомогательные функции работают без изменений на токене из вашего собственного приложения Meta.
{
"platform": "instagram",
"graph_api_base": "https://graph.instagram.com/<VERSION>",
"account_id_on_meta": "<IG_ID>",
"access_token": null,
"token_note": "Meta's terms do not allow handing this account's access token to other apps, so it is not shown. ..."
}Как выполнить те же задачи через коннектор MCP?
Попросив ассистента или вызвав инструменты самостоятельно. publish_instagram_post создаёт и публикует контейнер, дожидаясь обработки видео, или планирует публикацию через scheduled_at до 90 дней вперёд; reply_to_comment отвечает публично или в личные сообщения с private, равным true; get_social_insights передаёт названия метрик напрямую в Meta; а set_social_webhook_destination пересылает комментарии, упоминания и личные сообщения на ваш эндпоинт, подписанные X-EC-Signature.
[
{
"name": "publish_instagram_post",
"arguments": {
"account_id": "<from list_social_accounts>",
"type": "REELS",
"video_url": "https://cdn.example.com/launch.mp4",
"caption": "Launch day.",
"scheduled_at": "2026-11-06T09:00:00-03:00"
}
},
{
"name": "list_social_comments",
"arguments": { "account_id": "<ACCOUNT_ID>", "post_id": "<IG_MEDIA_ID>" }
},
{
"name": "reply_to_comment",
"arguments": { "account_id": "<ACCOUNT_ID>", "comment_id": "<IG_COMMENT_ID>", "text": "Prices are in our bio link." }
},
{
"name": "get_social_insights",
"arguments": {
"account_id": "<ACCOUNT_ID>",
"metrics": ["reach", "views", "accounts_engaged"],
"period": "day",
"params": { "metric_type": "total_value" }
}
},
{
"name": "set_social_webhook_destination",
"arguments": { "account_id": "<ACCOUNT_ID>", "url": "https://hooks.example.com/instagram" }
}
]Распространённые ошибки
- Хеширование разобранного JSON. Meta подписывает сырые байты, поэтому парсер JSON-тела фреймворка ломает проверку X-Hub-Signature-256: сохраняйте сырое тело и разбирайте его потом.
- Повторный вызов media_publish после тайм-аута без проверки. Если status_code контейнера равен PUBLISHED, публикация уже опубликована.
- Чтение кода 4 как ограничения частоты без подкода. С 2207051 это означает, что Instagram подозревает спам, и повторная попытка повторяет действие, которое только что было ограничено.
- Отправка секрета приложения или токена из кода браузера или мобильного приложения. Meta указывает, что запросы с секретом приложения должны выполняться только в серверном коде.
От US$ 9 до US$ 0,75 за подключение в месяц, снижаясь по мере добавления подключений, первые 3 дня бесплатно.
Часто задаваемые вопросы
Нужен ли SDK для вызова Instagram API?
Нет. Каждый вызов представляет собой HTTPS-запрос с токеном доступа, поэтому достаточно requests в Python или fetch в Node.js, как показано в примерах на этой странице.
Почему media_publish падает сразу после создания контейнера Reel?
Видео ещё обрабатывается: ошибка 9007 с подкодом 2207027. Проверяйте status_code контейнера раз в минуту и публикуйте, когда он станет FINISHED.
Какую версию API должен использовать код?
Ту, которую Meta ещё поддерживает: v26.0 самая новая, а каждая версия действует не менее двух лет. Вызов удалённой версии выполняется на ближайшей более старой версии, которая ещё доступна.
Сколько стоит easyCoexistence за доступ к API аккаунта Instagram?
Каждый аккаунт Instagram составляет одно подключение: от US$ 9 до US$ 0,75 за подключение в месяц, снижаясь по мере добавления подключений, первые 3 дня бесплатно.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на