Python ve Node.js'te Instagram API: çalışan örnekler
Instagram API yalnızca HTTPS gerektirir; bu yüzden Python'un requests paketi ve Node.js'in yerleşik fetch fonksiyonu yeterlidir: POST /<IG_ID>/media ve ardından media_publish yayınlar, /<IG_MEDIA_ID>/comments ile /<IG_COMMENT_ID>/replies yorumları okuyup yanıtlar, /insights metrikleri döndürür ve bir webhook, ham gövdenin HMAC-SHA256 değeriyle doğrulanır. Her hata, yeniden denemenin işe yarayıp yaramayacağını belirleyen bir kod ve alt kod taşır.
easyCoexistence, aynı işleri Claude, ChatGPT veya kendi ajanınız için MCP araçları olarak çalıştırır; token kendi tarafında kalır: publish_instagram_post, reply_to_comment, get_social_insights ve set_social_webhook_destination, Meta'nın resmi API'si üzerinde.
En son Graph API sürümü 29 Temmuz 2026'da tanıtıldı; v25.0 29 Temmuz 2028'e kadar kullanılabilir kalır.
Meta'nın önerdiği kontrol sıklığı: bir video container'ının status_code değeri en fazla 5 dakika boyunca denetlenir.
Tek bir GET /<IG_MEDIA_ID>/comments isteğinin döndürdüğü en çok yorum sayısı; yanıtlar yalnızca alan genişletmesiyle gelir.
Geçici bir yayınlama hatası; Meta, 30 saniye ile 2 dakika arasında 1 ila 2 kez yeniden denemeyi öneriyor.
X-Hub-Signature-256 içindeki önek; uygulama sırrıyla anahtarlanmış payload'un HMAC-SHA256 değerinden önce gelir.
Örnekler neye ihtiyaç duyar?
Bir çalışma ortamı, bir token ve dört değer. Örnekler, Instagram Login ile graph.instagram.com üzerinden Instagram API'yi çağırır; Unified Login uygulaması aynı yolları, hesabın ID'siyle ve Facebook Login'in Graph sunucusunda, Business Integration System User token'ıyla kullanır. Python'da requests paketine ek olarak webhook için Flask gerekir; Node.js ise yerleşik fetch için 18 veya üstü sürüm gerektirir.
- GRAPH: https://graph.instagram.com/v26.0, sunucu adresi ve API sürümü.
IG_ID: profesyonel hesabın ID'si, GET /me çağrısının döndürdüğüuser_id.- TOKEN: sunucuda tutulan uzun ömürlü bir Instagram User erişim token'ı.
APP_SECRETveVERIFY_TOKEN: webhook isteklerini doğrulamak için.
Python'da API'yi nasıl çağırır ve hataları nasıl yönetirsiniz?
Python örneklerinin ortak kullandığı tek bir yardımcı fonksiyon aracılığıyla. Token, access_token alanında gönderilir; Meta'nın kodu, alt kodu ve fbtrace_id değeriyle MetaError fırlatır ve yalnızca Meta'nın geçici olarak nitelendirdiği durumları yeniden dener: 1 ve 2 kodları, 4, 17 ve 80002 sınırlama kodları ile 2207001, 2207003, 2207008 ve 2207032 alt kodları. 2207051 alt koduyla gelen 4 kodu şüpheli spam anlamına gelir, bu yüzden hemen durur.
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))Node.js'te API'yi nasıl çağırır ve hataları nasıl yönetirsiniz?
Aynı yardımcı fonksiyonla, Node.js 18 veya üstü için; bağımlılık olmadan fetch kullanır. Kısıtlanmış bir çağrı, Meta'nın X-Business-Use-Case-Usage başlığında dakika cinsinden bildirdiği estimated_time_to_regain_access süresini bekler; bu başlık yoksa 60 saniye bekler, çünkü Meta kısıtlama sırasında yapılan çağrıları da sayar. needsNewToken, hiçbir yeniden denemenin çözemeyeceği 190 ve 102 kodlarını işaretler.
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'da fotoğraf ve Reel nasıl yayınlanır?
İkisi de container akışını izler. Bir fotoğraf container'ı hemen hazır olur, bu yüzden media_publish hemen ardından gelir. Reel'in videosu önce işlenir: fonksiyon, Meta'nın önerdiği gibi en fazla 5 dakika boyunca her dakika status_code değerini kontrol eder, FINISHED değerinde yayınlar ve ERROR ya da EXPIRED değerinde durur. Görseller JPEG olmalı ve medya herkese açık bir URL'de bulunmalıdır.
# 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'te fotoğraf ve Reel nasıl yayınlanır?
Aynı iki fonksiyon, her biri yeni medya ID'sini döndürür. Beş kontrolden sonra hâlâ IN_PROGRESS durumunda olan bir container, oluşturulmasından 24 saat sonrasına kadar geçerli kalır; bu yüzden hata mesajı onu daha sonra yeniden kontrol etmeyi söyler ve hesabın günde 400 limitine karşı ikinci bir container oluşturmaya gerek kalmaz.
// 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'da yorumları nasıl okur ve yanıtlarsınız?
GET /<IG_MEDIA_ID>/comments, istek başına en fazla 50 adet olmak üzere, en yeni önce olacak şekilde üst düzey yorumları döndürür; POST /<IG_COMMENT_ID>/replies ise birine herkese açık bir yanıt gönderir. Fonksiyon, her yanıtın metnini sizin bir geri çağırma fonksiyonunuzdan ister ve bu fonksiyonun bir şey döndürmediği yorumları atlar. Gizlenmiş yorumlara yanıt verilemez ve bir yanıta verilen yanıt, üst düzey yoruma eklenir.
# 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'te yorumları nasıl okur ve yanıtlarsınız?
Node.js'te aynı döngü. Her iki çağrı da instagram_business_basic ve instagram_business_manage_comments izinlerini kullanır; username alanı ikincisini gerektirir. Bunun yerine özel olarak yanıtlamak için POST /<IG_ID>/messages ve recipient.comment_id, yorum yapana yorumdan itibaren 7 gün içinde tek bir DM gönderir; takip mesajı ise kişi yanıt verene kadar beklemek zorundadır.
// 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'da insights nasıl okunur?
Hesap için insights istekleri period=day ve metric_type=total_value ister; her metrik ardından total_value.value döndürür; bir gönderinin insights yanıtı values[0].value değerini bildirir. Örnek, hesap için reach, views ve accounts_engaged, bir gönderi ya da Reel için ise Meta'nın referansının her ikisi için listelediği reach, views, likes, comments, saved ve shares metriklerini ister. Verisi olmayan bir metrik 0 olarak döndürülmek yerine dışarıda bırakılır.
# 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'te insights nasıl okunur?
Node.js'te aynı iki istek, her biri metrik adına göre anahtarlanmış bir nesne döndürür. Hiçbiri breakdown göndermez: Meta, bir metriğin desteklemediği bir breakdown istenirse isteğin bilinmeyen bir hatayla başarısız olacağını ve insights verilerinin 48 saate kadar gecikebileceğini uyarır; bu yüzden yeni gönderileri daha sonra yeniden okuyun.
// 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'da bir webhook nasıl doğrulanır?
Flask ile, aynı yolda iki rotayla. GET, Meta'nın doğrulama isteğini yanıtlar: hub.mode subscribe ve hub.verify_token eşleştiğinde hub.challenge değerini düz metin olarak döndürür; aksi halde 403 döner. POST, ham gövdenin uygulama sırrıyla hesaplanmış HMAC-SHA256 değerinin başına sha256= ekleyerek bir özet üretir, bunu X-Hub-Signature-256 ile sabit süreli bir karşılaştırmayla kıyaslar ve yavaş işlemler başlamadan önce 200 ile yanıt verir.
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 "", 200Node.js'te bir webhook nasıl doğrulanır?
Çerçevesiz, yerleşik http modülüyle. Gövde, herhangi bir ayrıştırma yapılmadan önce ham bayt olarak toplanır; çünkü ayrıştırılıp yeniden serileştirilmiş bir gövde, Meta'nın hesapladığı imzayla artık eşleşmez. Meta, başarısız bir bildirimi 36 saate kadar yeniden dener; bu yüzden işleyici, daha önce işlediği olayları da atlamalıdır.
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);Kod hangi Meta hatalarını yeniden denemeli?
Yalnızca geçici olanları; çünkü diğerleri, dosya, URL, izin ya da hesabın durumu değişene kadar aynı yanıtı verir. Meta'nın hata referansları, yukarıdaki yardımcı fonksiyonların ayırt ettiği her kod için yapılacak işlemi verir:
easyCoexistence'ın kimlik bilgileriyle aynı kodu nasıl çalıştırırsınız?
Bunu easyCoexistence'ın token'ı ile çalıştıramazsınız: Instagram token'ları asla verilmez (Meta'nın şartları), bu yüzden get_social_credentials ve Partner API'nin GET /api/v1/channels/:id?credentials=1 çağrısı hesabın ID'sini ve API tabanını token olmadan döndürür. Aynı işler bunun yerine Claude, ChatGPT veya başka bir MCP istemcisi üzerinden MCP araçları olarak çalışır; yukarıdaki yardımcı fonksiyonlar ise kendi Meta uygulamanızdan aldığınız bir token ile hiçbir değişiklik olmadan çalışır.
{
"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. ..."
}Aynı işleri MCP bağlayıcısıyla nasıl yaparsınız?
Asistana sorarak ya da araçları kendiniz çağırarak. publish_instagram_post, container'ı oluşturur ve yayınlar; video işlenirken bekler ya da scheduled_at ile en fazla 90 gün ileriye zamanlar. reply_to_comment herkese açık yanıt verir ya da private değeri true olduğunda DM ile özel olarak yanıtlar; get_social_insights metrik adlarını doğrudan Meta'ya iletir; set_social_webhook_destination ise yorumları, bahsetmeleri ve DM'leri X-EC-Signature ile imzalanmış olarak sizin uç noktanıza iletir.
[
{
"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" }
}
]Yaygın hatalar
- Ayrıştırılmış JSON'un hash'ini almak. Meta ham baytları imzalar; bu yüzden bir çerçevenin JSON gövde ayrıştırıcısı X-Hub-Signature-256 kontrolünü bozar. Ham gövdeyi saklayın, ayrıştırmayı sonra yapın.
- Zaman aşımından sonra bakmadan media_publish çağrısını yeniden yapmak. Container'ın status_code değeri PUBLISHED ise gönderi zaten canlıdır.
- Alt kod olmadan 4 kodunu sınırlama olarak okumak. 2207051 ile birlikte bu, Instagram'ın spam'den şüphelendiği anlamına gelir; yeniden deneme, az önce kısıtlanmış eylemi tekrarlar.
- Uygulama sırrını ya da token'ı tarayıcı veya mobil koddan göndermek. Meta, uygulama sırrı taşıyan isteklerin yalnızca sunucu tarafı kodda olması gerektiğini söyler.
Bağlantı başına aylık US$ 9 ile US$ 0.75 arasında, bağlantı ekledikçe düşer; ilk 3 gün ücretsiz deneme dahildir.
Sık sorulan sorular
Instagram API'yi çağırmak için SDK gerekir mi?
Hayır. Her çağrı, bir erişim token'ı içeren bir HTTPS isteğidir; bu sayfadaki örneklerde gösterildiği gibi Python'daki requests ya da Node.js'teki fetch yeterlidir.
Reel container'ı oluşturulduktan hemen sonra media_publish neden başarısız olur?
Video hâlâ işleniyor: 2207027 alt koduyla 9007 hatası. Container'ın status_code değerini dakikada bir kontrol edin ve FINISHED değerini okuduğunda yayınlayın.
Kod hangi API sürümünü kullanmalı?
Meta'nın hâlâ sunduğu bir sürüm: v26.0 en yenisidir ve her sürüm en az iki yıl yaşar. Kaldırılmış bir sürüme yapılan çağrı, hâlâ kullanılabilen bir sonraki en eski sürümde çalışır.
easyCoexistence bir Instagram hesabına API erişimi için ne kadar tutar?
Her Instagram hesabı bir bağlantıdır: bağlantı başına aylık US$ 9 ile US$ 0.75 arasında, bağlantı ekledikçe düşer; ilk 3 gün ücretsiz deneme dahildir.
Okumaya devam edin
İlk kanalınızı iki dakikada bağlayın.
Beklemeniz gereken platform incelemesi yok. WhatsApp, Instagram, TikTok veya başka bir kanalı bağlayın, ardından yapay zekânızdan paylaşım yapmasını, yanıtlamasını ya da rapor vermesini isteyin ve işini izleyin.
- 3 gün ücretsiz
- İstediğiniz zaman iptal
- Yalnızca resmi API'ler
- 7/24 izleniyor
Doğrulama tarihi