Instagram API Pythonilla ja Node.js:llä: toimivia esimerkkejä
Instagram API tarvitsee vain HTTPS:n, joten Pythonin requests-kirjasto ja Node.js:n sisäänrakennettu fetch riittävät: POST /<IG_ID>/media ja media_publish julkaisevat, /<IG_MEDIA_ID>/comments ja /<IG_COMMENT_ID>/replies lukevat kommentit ja vastaavat niihin, /insights palauttaa mittarit, ja webhook tarkistetaan pyynnön raakasisällön HMAC-SHA256-tiivisteen avulla. Jokaisella virheellä on koodi ja alikoodi, joiden perusteella ratkeaa, auttaako uudelleenyritys.
easyCoexistence ajaa samat tehtävät MCP-työkaluina Claudelle, ChatGPT:lle tai omalle agentillesi, ja token pysyy sen puolella: publish_instagram_post, reply_to_comment, get_social_insights ja set_social_webhook_destination Metan virallisella API:lla.
Uusin Graph API -versio, julkaistu 29. heinäkuuta 2026; v25.0 pysyy saatavilla 29. heinäkuuta 2028 asti.
Kuinka tiheästi Meta suosittelee tarkistamaan videokontin status_code-kentän, enintään 5 minuuttia.
Eniten kommentteja, jotka yksi GET /<IG_MEDIA_ID>/comments-pyyntö palauttaa; vastaukset tulevat vain kenttälaajennuksen kautta.
Väliaikainen julkaisuvirhe, jota Meta suosittelee yrittämään uudelleen 1–2 kertaa 30 sekunnin ja 2 minuutin välillä.
X-Hub-Signature-256-otsakkeen etuliite, joka edeltää sisällön HMAC-SHA256-tiivistettä, laskettu sovelluksen salaisuudella.
Mitä esimerkit tarvitsevat?
Ajoympäristön, tokenin ja neljä arvoa. Esimerkit kutsuvat Instagram API:a Instagram Loginilla osoitteessa graph.instagram.com; Unified Login -sovellus käyttää samoja polkuja tilin ID:llä Facebook Loginin Graph-isännällä ja sen Business Integration System User -tokenilla. Python tarvitsee requests-paketin ja webhookin tarkistamiseen Flaskin, Node.js:ssä tarvitaan versio 18 tai uudempi sisäänrakennettua fetchiä varten.
- GRAPH: https://graph.instagram.com/v26.0, isäntä ja API-versio.
IG_ID: ammattitilin ID, eliuser_id, jonka GET /me palauttaa.- TOKEN: pitkäikäinen Instagram User access token, joka säilytetään palvelimella.
APP_SECRETjaVERIFY_TOKEN: webhook-pyyntöjen tarkistamiseen.
Miten kutsut API:a ja käsittelet virheet Pythonilla?
Yhden apufunktion kautta, jonka Python-esimerkit jakavat. Se lähettää tokenin nimellä access_token, nostaa MetaError-virheen Metan koodilla, alikoodilla ja fbtrace_id:llä, ja yrittää uudelleen vain sitä, mitä Meta kutsuu väliaikaiseksi: koodit 1 ja 2, rajoituskoodit 4, 17 ja 80002 sekä alikoodit 2207001, 2207003, 2207008 ja 2207032. Koodi 4 alikoodilla 2207051 tarkoittaa epäiltyä roskapostia, joten se pysähtyy heti.
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))Miten kutsut API:a ja käsittelet virheet Node.js:llä?
Samalla apufunktiolla Node.js-versiolle 18 tai uudemmalle, käyttäen fetchiä ilman riippuvuuksia. Rajoitettu kutsu odottaa estimated_time_to_regain_access-kentän ilmoittamat minuutit, jotka Meta raportoi X-Business-Use-Case-Usage-otsakkeessa, tai 60 sekuntia ilman sitä, koska Meta laskee rajoituksen aikana tehdyt kutsut. needsNewToken merkitsee koodit 190 ja 102, joita mikään uudelleenyritys ei korjaa.
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");
}Miten julkaiset kuvan ja Reelin Pythonilla?
Molemmat seuraavat kontin kulkua. Kuvakontti on valmis heti, joten media_publish tulee sen jälkeen suoraan. Reelin video käsitellään ensin: funktio tarkistaa status_code-kentän kerran minuutissa enintään 5 minuuttia, kuten Meta suosittelee, julkaisee kun arvo on FINISHED ja pysähtyy, jos arvo on ERROR tai EXPIRED. Kuvien on oltava JPEG-muodossa ja median pitää olla julkisessa URL-osoitteessa.
# 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")Miten julkaiset kuvan ja Reelin Node.js:llä?
Samat kaksi funktiota, jotka kumpikin palauttavat uuden median ID:n. Kontti, joka on yhä IN_PROGRESS-tilassa viiden tarkistuksen jälkeen, pysyy voimassa 24 tuntia luomisestaan, joten virhe kehottaa tarkistamaan sen myöhemmin. Näin vältetään toisen kontin luominen tilin päivittäistä 400 kontin rajaa vastaan.
// 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`);
}Miten luet kommentit ja vastaat Pythonilla?
GET /<IG_MEDIA_ID>/comments palauttaa ylimmän tason kommentit uusimmasta vanhimpaan, enintään 50 per pyyntö, ja POST /<IG_COMMENT_ID>/replies julkaisee yhteen niistä julkisen vastauksen. Funktio kysyy jokaiselle kommentille vastauksen tekstin takaisinkutsulla, jonka annat, ja ohittaa kommentit, joille se ei palauta mitään. Piilotettuihin kommentteihin ei voi vastata, ja vastaus vastaukseen päätyy ylimmän tason kommentin alle.
# 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)Miten luet kommentit ja vastaat Node.js:llä?
Sama silmukka Node.js:ssä. Molemmat kutsut vaativat oikeudet instagram_business_basic ja instagram_business_manage_comments, ja username-kenttä vaatii jälkimmäisen. Jos haluat vastata yksityisesti, POST /<IG_ID>/messages ja recipient.comment_id lähettävät kommentoijalle yhden yksityisviestin (DM) 7 päivän sisällä kommentista, ja seurantaviesti odottaa, kunnes hän vastaa.
// 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));Miten luet tilastot Pythonilla?
Tilin tilastot vaativat parametrit period=day ja metric_type=total_value, jolloin jokainen mittari palauttaa total_value.value-arvon; julkaisun tilastot palauttavat values[0].value-arvon. Esimerkki pyytää tilille mittarit reach, views ja accounts_engaged sekä julkaisulle tai Reelille mittarit reach, views, likes, comments, saved ja shares, jotka Metan viiteasiakirja listaa molemmille. Mittaria, jolla ei ole dataa, ei palauteta arvona 0 vaan jätetään pois.
# 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}Miten luet tilastot Node.js:llä?
Samat kaksi pyyntöä Node.js:ssä, joista kumpikin palauttaa olion, jonka avaimena on mittarin nimi. Kumpikaan ei lähetä breakdown-parametria: Meta varoittaa, että sen pyytäminen mittarilta, joka ei sitä tue, epäonnistuu tuntemattomalla virheellä. Lisäksi tilastodata voi jäljessä jopa 48 tuntia, joten lue uusimmat julkaisut myöhemmin uudelleen.
// 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]));
}Miten vahvistat webhookin Pythonilla?
Flaskilla kahdella reitillä samassa polussa. GET vastaa Metan vahvistuspyyntöön: kun hub.mode on subscribe ja hub.verify_token täsmää, se palauttaa hub.challenge-arvon pelkkänä tekstinä, muuten 403. POST laskee sha256= sekä sovelluksen salaisuudella lasketun HMAC-SHA256-tiivisteen raakasisällöstä, vertaa sitä X-Hub-Signature-256-otsakkeeseen vakioajassa ja vastaa 200 ennen kuin mitään hidasta työtä alkaa.
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 "", 200Miten vahvistat webhookin Node.js:llä?
Sisäänrakennetulla http-moduulilla ilman kehystä. Runko kerätään raakoina tavuina ennen kuin mikään jäsentää sitä, koska jäsennetty ja uudelleen sarjallistettu runko ei enää vastaa Metan laskemaa allekirjoitusta. Meta yrittää uudelleen epäonnistunutta ilmoitusta jopa 36 tuntia, joten käsittelijän kannattaa ohittaa myös tapahtumat, jotka se on jo käsitellyt.
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);Mitä Metan virheitä koodin pitäisi yrittää uudelleen?
Vain väliaikaiset, koska muut antavat saman vastauksen, kunnes jokin muuttuu: tiedosto, URL-osoite, oikeus tai tilin tila. Metan virheviitteet antavat toimenpiteen jokaiselle koodille, jonka yllä olevat apufunktiot erottavat:
Miten ajat saman koodin easyCoexistencen tunnuksilla?
Sitä ei voi ajaa easyCoexistencen tokenilla: Instagram-tokeneita ei koskaan luovuteta (Metan ehdot), joten get_social_credentials ja Partner API:n GET /api/v1/channels/:id?credentials=1 palauttavat tilin ID:n ja API-perusosoitteen ilman tokenia. Samat tehtävät toimivat sen sijaan MCP-työkaluina Clauden, ChatGPT:n tai muun MCP-asiakkaan kautta, ja yllä olevat apufunktiot toimivat muuttumattomina oman Meta-sovelluksesi tokenilla.
{
"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. ..."
}Miten teet samat tehtävät MCP-liittimen kautta?
Pyytämällä avustajaa tai kutsumalla työkaluja itse. publish_instagram_post luo ja julkaisee kontin odottaen, kun video käsitellään, tai ajastaa sen scheduled_at-arvolla enintään 90 päivää eteenpäin; reply_to_comment vastaa julkisesti tai yksityisesti DM:llä, kun private on true; get_social_insights välittää mittarien nimet suoraan Metalle; ja set_social_webhook_destination välittää kommentit, maininnat ja DM:t sinun päätepisteeseesi, allekirjoitettuna X-EC-Signature-otsakkeella.
[
{
"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" }
}
]Yleiset virheet
- Jäsennetyn JSON:n tiivistäminen. Meta allekirjoittaa raakatavut, joten kehyksen JSON-runkojäsennin rikkoo X-Hub-Signature-256-tarkistuksen; säilytä raakasisältö ja jäsennä se vasta sen jälkeen.
- media_publishin kutsuminen uudelleen aikakatkaisun jälkeen katsomatta. Jos kontin status_code on PUBLISHED, julkaisu on jo näkyvissä.
- Koodin 4 lukeminen rajoituksena ilman alikoodia. Alikoodilla 2207051 se tarkoittaa, että Instagram epäilee roskapostia, ja uudelleenyritys toistaa juuri sen toimen, jonka Instagram juuri rajoitti.
- Sovelluksen salaisuuden tai tokenin lähettäminen selaimen tai mobiilikoodista. Meta sanoo, että sovelluksen salaisuutta sisältävät pyynnöt kuuluvat vain palvelinpuolen koodiin.
US$ 9:stä US$ 0,75:een per yhteys kuukaudessa, kun yhteyksiä lisää, ensimmäiset 3 päivää ovat ilmaista kokeilua.
Usein kysytyt kysymykset
Tarvitsenko SDK:ta, jotta voin kutsua Instagram API:a?
Ei. Jokainen kutsu on HTTPS-pyyntö tokenilla, joten requests Pythonissa tai fetch Node.js:ssä riittää, kuten tämän sivun esimerkit näyttävät.
Miksi media_publish epäonnistuu heti Reel-kontin luomisen jälkeen?
Video on yhä käsittelyssä: virhe 9007 alikoodilla 2207027. Tarkista kontin status_code kerran minuutissa ja julkaise, kun arvo on FINISHED.
Mitä API-versiota koodin pitäisi käyttää?
Sellainen, jota Meta yhä tarjoaa: v26.0 on uusin ja jokainen versio on voimassa vähintään kaksi vuotta. Poistetun version kutsu siirtyy seuraavaksi vanhimpaan saatavilla olevaan versioon.
Mitä easyCoexistence maksaa API-käytöstä Instagram-tilille?
Jokainen Instagram-tili on yksi yhteys: US$ 9:stä US$ 0,75:een per yhteys kuukaudessa, kun yhteyksiä lisää, ensimmäiset 3 päivää ovat ilmaista kokeilua.
Lue lisää
Yhdistä ensimmäinen kanavasi kahdessa minuutissa.
Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.
- 3 päivää ilmaiseksi
- Peruuta milloin tahansa
- Vain viralliset API:t
- Valvottu 24/7
Vahvistettu