Conectați-văÎncepeți perioada de probă gratuită
easyCoexistence API-uri oficiale

API-ul Instagram în Python și Node.js: exemple practice

API-ul Instagram nu cere nimic în plus față de HTTPS, deci requests din Python și fetch-ul integrat în Node.js sunt suficiente: POST /<IG_ID>/media urmat de media_publish publică, /<IG_MEDIA_ID>/comments și /<IG_COMMENT_ID>/replies citesc și răspund la comentarii, /insights returnează metricile, iar un webhook se verifică printr-un HMAC-SHA256 al corpului brut. Fiecare eroare are un cod și un subcod care decid dacă o reîncercare poate ajuta.

easyCoexistence rulează aceleași sarcini ca unelte MCP pentru Claude, ChatGPT sau propriul agent, cu token-ul păstrat de partea sa: publish_instagram_post, reply_to_comment, get_social_insights și set_social_webhook_destination, prin API-ul oficial al Meta.

v26.0

Cea mai recentă versiune a Graph API, lansată pe 29 iulie 2026; v25.0 rămâne disponibilă până pe 29 iulie 2028.

Once a minute

Cât de des sugerează Meta să verificați status_code-ul unui container video, timp de cel mult 5 minute.

50

Cele mai multe comentarii pe care le returnează o singură cerere GET /<IG_MEDIA_ID>/comments; răspunsurile vin doar prin extinderea câmpurilor.

2207008

O eroare temporară de publicare, pentru care Meta recomandă 1 până la 2 reîncercări în interval de 30 de secunde până la 2 minute.

sha256=

Prefixul din X-Hub-Signature-256, dinaintea HMAC-SHA256 al payload-ului cheiat cu secretul aplicației.

De ce au nevoie exemplele?

Un runtime, un token și patru valori. Exemplele apelează API-ul Instagram cu Instagram Login pe graph.instagram.com; o aplicație Unified Login folosește aceleași căi cu ID-ul contului, pe host-ul Graph al Facebook Login, cu token-ul său Business Integration System User. Python are nevoie de pachetul requests, plus Flask pentru webhook, iar Node.js are nevoie de versiunea 18 sau mai nouă pentru fetch-ul integrat.

  • GRAPH: https://graph.instagram.com/v26.0, host-ul și versiunea API-ului.
  • IG_ID: ID-ul contului profesional, user_id-ul pe care îl returnează GET /me.
  • TOKEN: un token Instagram User de lungă durată, păstrat pe server.
  • APP_SECRET și VERIFY_TOKEN: pentru verificarea cererilor de webhook.

Cum apelați API-ul și gestionați erorile în Python?

Printr-un singur helper, pe care îl folosesc în comun exemplele Python de mai jos. Trimite token-ul ca access_token, ridică MetaError cu codul, subcodul și fbtrace_id ale Meta și reîncearcă doar ceea ce Meta numește temporar: codurile 1 și 2, codurile de limitare 4, 17 și 80002, și subcodurile 2207001, 2207003, 2207008 și 2207032. Codul 4 cu subcodul 2207051 înseamnă spam suspectat, deci oprește imediat.

Python: the shared helper (requests)
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))

Cum apelați API-ul și gestionați erorile în Node.js?

Cu același helper pentru Node.js 18 sau mai nou, care folosește fetch și nicio dependență. Un apel limitat așteaptă estimated_time_to_regain_access, numărul de minute raportat de Meta în antetul X-Business-Use-Case-Usage, sau 60 de secunde dacă acesta lipsește, pentru că Meta numără și apelurile făcute în timpul limitării. needsNewToken semnalează codurile 190 și 102, pe care nicio reîncercare nu le poate remedia.

Node.js: the shared helper (fetch, ES module)
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");
}

Cum publicați o fotografie și un Reel în Python?

Ambele urmează fluxul de containere. Un container de fotografie este gata imediat, deci media_publish vine direct după el. Videoclipul unui Reel este procesat mai întâi: funcția verifică status_code o dată pe minut, timp de cel mult 5 minute, cum sugerează Meta, publică la FINISHED și se oprește la ERROR sau EXPIRED. Imaginile trebuie să fie JPEG, iar media trebuie să fie la un URL public.

Python: a photo and a Reel
# 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")

Cum publicați o fotografie și un Reel în Node.js?

Aceleași două funcții, fiecare returnând ID-ul noului media. Un container aflat încă în IN_PROGRESS după cinci verificări rămâne valid până la 24 de ore de la creare, așa că eroarea spune să fie verificat din nou mai târziu, ceea ce evită crearea unui al doilea container, din cele 400 pe zi permise contului.

Node.js: a photo and a Reel
// 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`);
}

Cum citiți comentariile și răspundeți în Python?

GET /<IG_MEDIA_ID>/comments returnează comentariile de nivel superior, cele mai noi primele, până la 50 pe cerere, iar POST /<IG_COMMENT_ID>/replies postează un răspuns public la unul dintre ele. Funcția cere de la callback-ul dumneavoastră textul fiecărui răspuns și sare peste comentariile pentru care nu returnează nimic. Comentariile ascunse nu pot primi răspuns, iar un răspuns la un răspuns ajunge la comentariul de nivel superior.

Python: read comments and reply
# 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)

Cum citiți comentariile și răspundeți în Node.js?

Aceeași buclă în Node.js. Ambele apeluri folosesc instagram_business_basic și instagram_business_manage_comments, iar câmpul username are nevoie de al doilea. Pentru a răspunde privat, POST /<IG_ID>/messages cu recipient.comment_id trimite comentatorului un singur mesaj direct (DM), în 7 zile de la comentariu, iar un mesaj ulterior așteaptă până când acesta răspunde.

Node.js: read comments and reply
// 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));

Cum citiți statisticile în Python?

Statisticile contului cer period=day cu metric_type=total_value, iar fiecare metrică raportează apoi total_value.value; statisticile unei postări raportează values[0].value. Exemplul cere reach, views și accounts_engaged pe cont, iar pentru o postare sau un Reel cere reach, views, likes, comments, saved și shares, pe care referința Meta le listează pentru ambele. O metrică fără date este omisă, nu returnată cu 0.

Python: account and post insights
# 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}

Cum citiți statisticile în Node.js?

Aceleași două cereri în Node.js, fiecare returnând un obiect cu cheia numelui metricii. Niciuna nu trimite un parametru breakdown: Meta avertizează că cererea unuia nesuportat de o metrică eșuează cu o eroare necunoscută, iar datele statisticilor pot întârzia până la 48 de ore, așa că recitiți postările recente mai târziu.

Node.js: account and post insights
// 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]));
}

Cum verificați un webhook în Python?

Cu Flask, în două rute pe aceeași cale. GET răspunde cererii de verificare a Meta: când hub.mode este subscribe și hub.verify_token se potrivește, returnează hub.challenge ca text simplu, iar altfel un 403. POST calculează sha256= plus HMAC-SHA256 al corpului brut cu secretul aplicației, îl compară cu X-Hub-Signature-256 în timp constant și răspunde cu 200 înainte ca vreo prelucrare lentă să înceapă.

Python: webhook verification and signature check (Flask)
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

Cum verificați un webhook în Node.js?

Cu modulul http integrat și fără framework. Corpul este colectat ca octeți bruți înainte ca ceva să îl parseze, pentru că un corp parsat și serializat din nou nu mai corespunde semnăturii calculate de Meta. Meta reîncearcă o notificare eșuată timp de până la 36 de ore, așa că un handler ar trebui să sară și peste evenimentele deja procesate.

Node.js: webhook verification and signature check (node:http)
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);

Ce erori Meta ar trebui să reîncerce codul?

Doar cele temporare, pentru că restul returnează același răspuns până când se schimbă ceva: fișierul, URL-ul, o permisiune sau starea contului. Referințele de erori ale Meta dau acțiunea pentru fiecare cod pe care helperii de mai sus le diferențiază:

1, 2Temporary or downtime: wait, then retry
4, 17, 80002Throttling: wait for estimated_time_to_regain_access, then retry
4 with 2207051Suspected spam: stop, since a retry repeats the action
2207001, 2207003, 2207032Server error, download timeout or failed container: try again
2207008Container briefly missing: retry 1 to 2 times within 2 minutes
190, 102Token expired or invalid: refresh it while valid, or sign in again
10, 200 to 299Permission missing or removed: request it at sign-in
25 with 2207050Account restricted: the owner acts in the Instagram app
9 with 2207042Daily publishing limit: try again the next day
9004 with 2207052Media not fetched from the URL: fix the link

Cum rulați același cod pe credențialele easyCoexistence?

Nu îl puteți rula cu token-ul easyCoexistence: token-urile Instagram nu se oferă niciodată (termenii Meta), deci get_social_credentials și GET /api/v1/channels/:id?credentials=1 al Partner API returnează ID-ul contului și baza API, fără token. În schimb, aceleași sarcini rulează ca unelte MCP, prin Claude, ChatGPT sau alt client MCP, iar helperii de mai sus rulează neschimbați cu un token din propria aplicație Meta.

What get_social_credentials returns for an Instagram account
{
  "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. ..."
}

Cum faceți aceleași sarcini prin conectorul MCP?

Cerând asistentului sau apelând singuri uneltele. publish_instagram_post creează și publică containerul, așteptând cât timp se procesează un videoclip, sau îl programează cu scheduled_at până la 90 de zile înainte; reply_to_comment răspunde public sau privat, prin mesaj direct (DM), cu private setat la true; get_social_insights transmite numele metricilor direct către Meta; iar set_social_webhook_destination trimite comentariile, mențiunile și DM-urile către endpoint-ul dumneavoastră, semnate cu X-EC-Signature.

MCP tool calls for the same jobs
[
  {
    "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" }
  }
]

Greșeli frecvente

  • Calcularea hash-ului pe JSON-ul parsat. Meta semnează octeții bruți, așa că parserul de corp JSON al unui framework strică verificarea X-Hub-Signature-256; păstrați corpul brut și parsați-l după aceea.
  • Apelarea din nou a media_publish după un timeout, fără verificare. Dacă status_code-ul containerului arată PUBLISHED, postarea este deja live.
  • Citirea codului 4 drept limitare, fără subcod. Cu 2207051 înseamnă că Instagram suspectează spam, iar o reîncercare repetă acțiunea pe care tocmai a restricționat-o.
  • Trimiterea secretului aplicației sau a token-ului din cod de browser sau mobil. Meta spune că cererile care poartă secretul aplicației aparțin doar codului de pe server.
Faceți acest lucru cu EasyCoexistence

De la US$ 9 până la US$ 0,75 per conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, cu primele 3 zile gratuite.

Întrebări frecvente

Am nevoie de un SDK pentru a apela API-ul Instagram?

Nu. Fiecare apel este o cerere HTTPS cu un token de acces, deci requests în Python sau fetch în Node.js este suficient, după cum arată exemplele de pe această pagină.

De ce eșuează media_publish imediat după crearea unui container de Reel?

Videoclipul încă se procesează: eroarea 9007 cu subcodul 2207027. Verificați status_code-ul containerului o dată pe minut și publicați când arată FINISHED.

Ce versiune a API-ului ar trebui să folosească codul?

Una pe care Meta o mai servește: v26.0 este cea mai recentă, iar fiecare versiune durează cel puțin doi ani. Un apel către o versiune eliminată rulează pe următoarea cea mai veche versiune încă disponibilă.

Cât costă easyCoexistence pentru accesul API la un cont Instagram?

Fiecare cont Instagram este o conexiune: de la US$ 9 până la US$ 0,75 per conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, cu primele 3 zile gratuite.

Continuați să citiți

Conectați primul canal în două minute.

Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.

  • 3 zile gratuit
  • Anulați oricând
  • Doar API-uri oficiale
  • Monitorizat 24/7

Verificat la