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 מחזיר מדדים, וחתימה של וובהוק (Webhook) נבדקת ב-HMAC-SHA256 של הגוף הגולמי. לכל שגיאה יש קוד שגיאה וגם subcode, ואלה קובעים אם ניסיון חוזר יכול לעזור.
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 של ה-payload, שמחושב עם app secret.
מה הדוגמאות צריכות?
סביבת הרצה, אסימון וארבעה ערכים. הדוגמאות קוראות ל-Instagram API דרך Instagram Login ב-graph.instagram.com. אפליקציית Unified Login משתמשת באותם נתיבים עם המזהה של החשבון, בכתובת Graph של Facebook Login ועם אסימון Business Integration System User. ב-Python צריך את חבילת requests וכן Flask לטיפול בוובהוק, וב-Node.js נדרשת גרסה 18 ומעלה לצורך fetch המובנה.
- GRAPH: https://graph.instagram.com/v26.0, שהוא המארח וגרסת הממשק.
IG_ID: מזהה החשבון המקצועי, ה-user_idש-GET /me מחזיר.- TOKEN: אסימון גישה (Access Token) ארוך טווח של Instagram User, ששומרים בצד השרת.
APP_SECRETוגםVERIFY_TOKEN: לבדיקת הבקשות הנכנסות לוובהוק.
איך קוראים ל-API ומטפלים בשגיאות ב-Python?
דרך פונקציית עזר אחת, שהדוגמאות ב-Python חולקות. היא שולחת את האסימון כ-access_token, מעלה MetaError הכולל את הקוד, את subcode ואת fbtrace_id של Meta, ומנסה שוב רק את מה ש-Meta מסווגת כזמני: קודים 1 ו-2, קודי ההגבלה 4, 17 ו-80002, ותת-הקודים 2207001, 2207003, 2207008 ו-2207032. קוד 4 עם subcode 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, כלומר לדקות שמדווחות בכותרת 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");
}איך מפרסמים תמונה וריל ב-Python?
שניהם עוברים באותו זרם קונטיינר. קונטיינר של תמונה מוכן מיד, ולכן media_publish בא מיד אחריו. הווידאו של ריל עובר עיבוד תחילה: הפונקציה בודקת את 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")איך מפרסמים תמונה וריל ב-Node.js?
אותן שתי פונקציות, שכל אחת מחזירה את מזהה המדיה החדש. קונטיינר שעדיין 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 שולח תשובה ציבורית לאחת מהן. הפונקציה מבקשת מ-callback שלכם את טקסט התשובה לכל תגובה, ומדלגת על תגובות שלא הוחזר להן טקסט. אי אפשר להשיב לתגובות מוסתרות, ותשובה לתשובה מופיעה תחת התגובה העליונה.
# 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, ולפוסט או לריל את 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 מזהירה שבקשה לפירוט שמדד אינו תומך בו נכשלת עם שגיאה לא ידועה, ושנתוני התובנות עשויים לפגר עד 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 מחזירים את מזהה החשבון ואת בסיס ה-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 כהגבלה ללא ה-subcode. עם 2207051 הוא אומר ש-Instagram חושדת בספאם, וניסיון חוזר מבצע מחדש את הפעולה שזה עתה הוגבלה.
- שליחת סוד האפליקציה או האסימון מקוד של דפדפן או אפליקציית מובייל. Meta אומרת שבקשות שנושאות את סוד האפליקציה שייכות לקוד בצד השרת בלבד.
US$ 9 עד US$ 0.75 לחיבור בחודש, וירד ככל שמוסיפים חיבורים, עם תקופת ניסיון של 3 ימים בחינם.
שאלות נפוצות
האם צריך SDK כדי לקרוא ל-Instagram API?
לא. כל קריאה היא בקשת HTTPS עם אסימון, ולכן ספריית requests ב-Python או fetch ב-Node.js מספיקים, כפי שהדוגמאות בעמוד הזה מראות.
למה media_publish נכשל מיד אחרי יצירת קונטיינר של ריל?
הווידאו עדיין בעיבוד: שגיאה 9007 עם subcode 2207027. בדקו את status_code של הקונטיינר פעם בדקה, ופרסמו כשהערך הוא FINISHED.
איזו גרסת API הקוד צריך להשתמש בה?
גרסה ש-Meta עדיין משרתת: v26.0 היא העדכנית, וכל גרסה זמינה לפחות שנתיים. קריאה לגרסה שהוסרה רצה על הגרסה הקודמת הקרובה ביותר שעדיין זמינה.
כמה עולה easyCoexistence לגישת API לחשבון Instagram?
כל חשבון Instagram הוא חיבור אחד: US$ 9 עד US$ 0.75 לחיבור בחודש, וירד ככל שמוסיפים חיבורים, עם תקופת ניסיון של 3 ימים בחינם.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-