Instagram API kwa Python na Node.js: mifano inayofanya kazi
Instagram API haihitaji chochote zaidi ya HTTPS, kwa hiyo requests ya Python na fetch iliyojengwa ndani ya Node.js zinatosha: POST /<IG_ID>/media kisha media_publish huchapisha, /<IG_MEDIA_ID>/comments na /<IG_COMMENT_ID>/replies husoma na kujibu maoni, /insights hurudisha vipimo, na webhook huthibitishwa kwa HMAC-SHA256 ya mwili ghafi. Kila hitilafu hubeba code na subcode zinazoamua kama jaribio jingine linaweza kusaidia.
easyCoexistence huendesha kazi zilezile kama zana za MCP kwa Claude, ChatGPT au wakala wako mwenyewe, huku token ikibaki upande wake: publish_instagram_post, reply_to_comment, get_social_insights na set_social_webhook_destination, kwenye API rasmi ya Meta.
Toleo la hivi karibuni la Graph API, lililotolewa tarehe 29 Julai 2026; v25.0 itabaki kupatikana hadi tarehe 29 Julai 2028.
Mara ngapi Meta inapendekeza kukagua status_code ya kontena la video, kwa si zaidi ya dakika 5.
Idadi kubwa zaidi ya maoni ambayo ombi moja la GET /<IG_MEDIA_ID>/comments hurudisha; majibu hurudi tu kupitia field expansion.
Hitilafu ya muda ya uchapishaji, ambayo Meta inasema ijaribiwe tena mara 1 hadi 2 ndani ya sekunde 30 hadi dakika 2.
Kiambishi katika X-Hub-Signature-256, kabla ya HMAC-SHA256 ya payload iliyofungwa kwa APP_SECRET.
Mifano inahitaji nini?
Mazingira ya kuendesha (runtime), tokeni na thamani nne. Mifano inaita Instagram API kupitia Instagram Login kwenye graph.instagram.com; programu ya Unified Login hutumia njia zilezile pamoja na ID ya akaunti, kwenye host ya Graph ya Facebook Login kwa tokeni yake ya Business Integration System User. Python inahitaji kifurushi cha requests, pamoja na Flask kwa webhook, na Node.js inahitaji toleo la 18 au jipya zaidi kwa fetch yake iliyojengwa ndani.
- GRAPH: https://graph.instagram.com/v26.0, host na toleo la API.
IG_ID: ID ya akaunti ya kitaalamu,user_idambayo GET /me hurudisha.- TOKEN: tokeni ya ufikiaji ya Instagram User ya muda mrefu, ihifadhiwe kwenye seva.
APP_SECRETnaVERIFY_TOKEN: kwa kukagua maombi ya webhook.
Unaitaje API na kushughulikia hitilafu kwa Python?
Kupitia kisaidizi kimoja, ambacho mifano ya Python hapa chini inakitumia pamoja. Kinatuma tokeni kama access_token, kinatupa MetaError pamoja na code, subcode na fbtrace_id ya Meta, na hujaribu tena yale tu Meta inayoyaita ya muda: code 1 na 2, code za kupunguza kasi (throttling) 4, 17 na 80002, na subcodes 2207001, 2207003, 2207008 na 2207032. Code 4 yenye subcode 2207051 inamaanisha spam inayoshukiwa, kwa hiyo linasimama mara moja.
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))Unaitaje API na kushughulikia hitilafu kwa Node.js?
Kwa kisaidizi kile kile kwa Node.js 18 au jipya zaidi, kinachotumia fetch bila maktaba za ziada. Wito uliozuiliwa kwa kasi husubiri estimated_time_to_regain_access, dakika ambazo Meta inaripoti kwenye header ya X-Business-Use-Case-Usage, au sekunde 60 bila hiyo, kwa sababu Meta inahesabu miito iliyofanywa wakati wa kuzuiliwa. needsNewToken huashiria code 190 na 102, ambazo hakuna jaribio tena linaloweza kurekebisha.
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");
}Unachapishaje picha na Reel kwa Python?
Zote mbili zinafuata mtiririko wa kontena. Kontena la picha liko tayari papo hapo, kwa hiyo media_publish inakuja mara moja baada yake. Video ya Reel huchakatwa kwanza: kazi hukagua status_code mara moja kwa dakika, hadi dakika 5, kama Meta inavyopendekeza, huchapisha ikiwa FINISHED na husimama ikiwa ERROR au EXPIRED. Picha lazima ziwe JPEG, na media iwe kwenye URL ya umma.
# 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")Unachapishaje picha na Reel kwa Node.js?
Kazi mbili zilezile, kila moja ikirudisha ID mpya ya media. Kontena lililobaki IN_PROGRESS baada ya ukaguzi tano hubaki halali hadi saa 24 baada ya kuundwa kwake, kwa hiyo hitilafu inasema ukaguzi ufanyike tena baadaye, jambo linaloepusha kuunda kontena la pili dhidi ya kikomo cha akaunti cha 400 kwa siku.
// 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`);
}Unasomaje maoni na kujibu kwa Python?
GET /<IG_MEDIA_ID>/comments hurudisha maoni ya ngazi ya juu, ya hivi karibuni kwanza, hadi 50 kwa ombi, na POST /<IG_COMMENT_ID>/replies huchapisha jibu la umma kwa moja yake. Kazi inauliza callback yako maandishi ya kila jibu na kuruka maoni ambayo haitoi jibu kwayo. Maoni yaliyofichwa hayawezi kujibiwa, na jibu kwa jibu huishia kwenye maoni ya ngazi ya juu.
# 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)Unasomaje maoni na kujibu kwa Node.js?
Mzunguko huohuo kwa Node.js. Miito yote miwili inatumia instagram_business_basic na instagram_business_manage_comments, na sehemu ya username inahitaji ya pili. Ili kujibu kwa faragha badala yake, POST /<IG_ID>/messages yenye recipient.comment_id hutuma DM moja kwa aliyetoa maoni, ndani ya siku 7 tangu maoni, na ujumbe wa kufuatilia husubiri hadi atakapojibu.
// 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));Unasomaje takwimu (insights) kwa Python?
Takwimu za akaunti huchukua period=day na metric_type=total_value, kisha kila kipimo huripoti total_value.value; takwimu za chapisho huripoti values[0].value. Mfano huomba reach, views na accounts_engaged kwenye akaunti, na reach, views, likes, comments, saved na shares kwenye chapisho au Reel, ambavyo rejeleo la Meta linaorodhesha kwa zote mbili. Kipimo kisicho na data huachwa badala ya kurudishwa kama 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}Unasomaje takwimu (insights) kwa Node.js?
Maombi yaleyale mawili kwa Node.js, kila moja ikirudisha kitu kinachotumia jina la kipimo kama ufunguo. Hakuna linalotuma mgawanyo (breakdown): Meta inaonya kwamba kuomba mgawanyo ambao kipimo hakiuungi mkono kunashindwa kwa hitilafu isiyojulikana, na data ya takwimu inaweza kuchelewa hadi saa 48, kwa hiyo soma machapisho ya hivi karibuni tena baadaye.
// 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]));
}Unathibitishaje webhook kwa Python?
Kwa Flask, kwenye njia mbili zilizo kwenye path moja. GET hujibu ombi la uthibitishaji la Meta: hub.mode ikiwa subscribe na hub.verify_token ikilingana, inarudisha hub.challenge kama maandishi matupu, na 403 vinginevyo. POST huhesabu sha256= pamoja na HMAC-SHA256 ya mwili ghafi kwa APP_SECRET, inalinganisha na X-Hub-Signature-256 kwa muda usiobadilika, na hujibu 200 kabla kazi nzito haijaanza.
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 "", 200Unathibitishaje webhook kwa Node.js?
Kwa moduli ya http iliyojengwa ndani na bila framework. Mwili unakusanywa kama baiti ghafi kabla ya chochote kuuchambua, kwa sababu mwili uliochambuliwa na kuandikwa upya haulingani tena na sahihi aliyoihesabu Meta. Meta hujaribu tena arifa iliyoshindwa kwa hadi saa 36, kwa hiyo kishughulikiaji kinapaswa pia kuruka matukio ambayo tayari yamechakatwa.
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);Msimbo unapaswa kujaribu tena hitilafu zipi za Meta?
Za muda tu, kwa sababu nyingine hurudisha jibu lilelile hadi kitu kibadilike: faili, URL, ruhusa au hali ya akaunti. Rejeleo la hitilafu za Meta linatoa hatua kwa kila code ambayo visaidizi hapo juu vinatofautisha:
Unaendeshaje msimbo huohuo kwa vitambulisho vya easyCoexistence?
Huwezi kuiendesha kwa token ya easyCoexistence: token za Instagram hazitolewi kamwe (masharti ya Meta), kwa hiyo get_social_credentials na GET /api/v1/channels/:id?credentials=1 ya Partner API hurudisha ID ya akaunti na API base bila token. Kazi zilezile huendeshwa kama zana za MCP badala yake, kupitia Claude, ChatGPT au mteja mwingine wa MCP, na visaidizi vilivyo hapo juu hufanya kazi bila mabadiliko kwa token kutoka programu yako mwenyewe ya 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. ..."
}Unafanyaje kazi hizohizo kupitia kiunganishi cha MCP?
Kwa kumwomba msaidizi, au kwa kuita zana wewe mwenyewe. publish_instagram_post huunda na kuchapisha kontena, ikisubiri video ikichakatwa, au huipangia ratiba kwa scheduled_at hadi siku 90 mbele; reply_to_comment hujibu hadharani, au kwa faragha kupitia DM ikiwa private ni true; get_social_insights hupeleka majina ya vipimo moja kwa moja kwa Meta; na set_social_webhook_destination husambaza maoni, kutajwa na DM kwenye endpoint yako, ikisainiwa kwa 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" }
}
]Makosa ya kawaida
- Kuhesabu hash ya JSON iliyochambuliwa. Meta husaini baiti ghafi, kwa hiyo kichambuzi cha mwili wa JSON cha framework huvunja ukaguzi wa X-Hub-Signature-256; weka mwili ghafi na uuchambue baadaye.
- Kuita media_publish tena baada ya muda kuisha bila kuangalia kwanza. Ikiwa status_code ya kontena inasoma PUBLISHED, chapisho tayari liko hewani.
- Kusoma code 4 kama throttling bila subcode. Ikiwa na 2207051 inamaanisha Instagram inashuku spam, na jaribio tena linarudia kitendo ambacho ndicho kilichowekewa vikwazo.
- Kutuma APP_SECRET au tokeni kutoka msimbo wa kivinjari au wa simu. Meta inasema maombi yenye APP_SECRET yanapaswa kuwa kwenye msimbo wa seva pekee.
US$ 9 hadi US$ 0.75 kwa kila muunganisho kwa mwezi, inashuka unapoongeza miunganisho, na siku 3 za kwanza ni bure.
Maswali yanayoulizwa mara kwa mara
Je, ninahitaji SDK kuita Instagram API?
Hapana. Kila wito ni ombi la HTTPS lenye tokeni ya ufikiaji, kwa hiyo requests ya Python au fetch ya Node.js zinatosha, kama mifano kwenye ukurasa huu inavyoonyesha.
Kwa nini media_publish inashindwa mara tu baada ya kontena la Reel kuundwa?
Video bado inachakatwa: hitilafu 9007 yenye subcode 2207027. Kagua status_code ya kontena mara moja kwa dakika na uchapishe itakaposoma FINISHED.
Msimbo unapaswa kutumia toleo gani la API?
Toleo ambalo Meta bado inatoa: v26.0 ndilo la hivi karibuni, na kila toleo hudumu angalau miaka miwili. Wito kwa toleo lililoondolewa hukimbia kwenye toleo la karibu zaidi lililo bado linapatikana.
easyCoexistence inagharimu kiasi gani kwa ufikiaji wa API kwa akaunti ya Instagram?
Kila akaunti ya Instagram ni muunganisho mmoja: US$ 9 hadi US$ 0.75 kwa kila muunganisho kwa mwezi, inashuka unapoongeza miunganisho, na siku 3 za kwanza ni bure.
Endelea kusoma
Unganisha chaneli yako ya kwanza ndani ya dakika mbili.
Hakuna ukaguzi wa majukwaa wa kusubiri. Unganisha WhatsApp, Instagram, TikTok au chaneli nyingine, kisha mwombe AI wako achapishe, ajibu au atoe ripoti, na uone akifanya kazi.
- Siku 3 bila malipo
- Ghairi wakati wowote
- API rasmi pekee
- Hufuatiliwa saa 24/7
Imethibitishwa kwenye