API do Instagram em Python e Node.js: exemplos funcionais
A API do Instagram não exige nada além de HTTPS, então requests do Python e o fetch nativo do Node.js dão conta. POST /<IG_ID>/media e depois media_publish publicam; /<IG_MEDIA_ID>/comments e /<IG_COMMENT_ID>/replies leem e respondem comentários; /insights retorna métricas; e um webhook é verificado com um HMAC-SHA256 do corpo bruto. Cada erro traz um code e um subcode que dizem se uma repetição pode ajudar.
A easyCoexistence executa as mesmas tarefas como ferramentas MCP para Claude, ChatGPT ou seu próprio agente, com o token mantido do lado dela: publish_instagram_post, reply_to_comment, get_social_insights e set_social_webhook_destination, pela API oficial da Meta.
A versão mais recente da Graph API, lançada em 29 de julho de 2026; a v25.0 continua disponível até 29 de julho de 2028.
Com que frequência a Meta sugere verificar o status_code de um container de vídeo, por no máximo 5 minutos.
Máximo de comentários que uma requisição GET /<IG_MEDIA_ID>/comments retorna; as respostas só vêm por expansão de campos.
Um erro temporário de publicação, para o qual a Meta indica repetir 1 a 2 vezes em 30 segundos a 2 minutos.
O prefixo em X-Hub-Signature-256, antes do HMAC-SHA256 do payload assinado com o app secret.
O que os exemplos precisam?
Um runtime, um token e quatro valores. Os exemplos chamam a API do Instagram com Instagram Login em graph.instagram.com; um app com Unified Login usa os mesmos caminhos com o ID da conta, no host Graph do Facebook Login e com o token Business Integration System User. O Python precisa do pacote requests, além do Flask para o webhook, e o Node.js precisa da versão 18 ou superior para seu fetch nativo.
- GRAPH: https://graph.instagram.com/v26.0, o host e a versão da API.
IG_ID: o ID da conta profissional, ouser_idque GET /me retorna.- TOKEN: um token de acesso de usuário do Instagram de longa duração, mantido no servidor.
APP_SECRETeVERIFY_TOKEN: para verificar as requisições do webhook.
Como chamar a API e tratar erros em Python?
Por meio de um único auxiliar, que os exemplos em Python abaixo compartilham. Ele envia o token como access_token, lança MetaError com o code, o subcode e o fbtrace_id da Meta, e repete apenas o que a Meta chama de temporário: os códigos 1 e 2, os códigos de limite de taxa 4, 17 e 80002, e os subcodes 2207001, 2207003, 2207008 e 2207032. O código 4 com subcode 2207051 indica suspeita de spam, então para imediatamente.
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))Como chamar a API e tratar erros em Node.js?
Com o mesmo auxiliar para Node.js 18 ou superior, usando fetch e sem dependências. Uma chamada limitada espera o estimated_time_to_regain_access, os minutos que a Meta informa no cabeçalho X-Business-Use-Case-Usage, ou 60 segundos sem ele, já que a Meta conta as chamadas feitas durante o limite. needsNewToken sinaliza os códigos 190 e 102, que nenhuma repetição resolve.
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");
}Como publicar uma foto e um Reel em Python?
Os dois seguem o fluxo de container. Um container de foto fica pronto de imediato, então media_publish vem logo em seguida. O vídeo de um Reel é processado primeiro: a função verifica o status_code uma vez por minuto por até 5 minutos, como a Meta sugere, publica ao receber FINISHED e para em ERROR ou EXPIRED. As imagens precisam ser JPEG, e a mídia tem que estar em uma URL pública.
# 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")Como publicar uma foto e um Reel em Node.js?
As mesmas duas funções, cada uma retornando o novo ID da mídia. Um container que ainda está IN_PROGRESS após cinco verificações continua válido por 24 horas após sua criação, então o erro pede para verificar de novo mais tarde, o que evita criar um segundo container contra o limite de 400 por dia da conta.
// 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`);
}Como ler comentários e responder em Python?
GET /<IG_MEDIA_ID>/comments retorna comentários de primeiro nível, do mais recente para o mais antigo, até 50 por requisição, e POST /<IG_COMMENT_ID>/replies publica uma resposta pública a um deles. A função pede a um callback seu o texto de cada resposta e ignora os comentários para os quais ele não retorna nada. Comentários ocultos não podem ser respondidos, e uma resposta a outra resposta vai para o comentário de primeiro nível.
# 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)Como ler comentários e responder em Node.js?
O mesmo laço em Node.js. As duas chamadas usam instagram_business_basic e instagram_business_manage_comments, e o campo username exige a segunda. Para responder em privado, POST /<IG_ID>/messages com recipient.comment_id envia ao autor do comentário uma DM, dentro de 7 dias do comentário, e uma mensagem de acompanhamento aguarda até ele responder.
// 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));Como ler insights em Python?
Os insights da conta usam period=day com metric_type=total_value, e cada métrica então informa total_value.value; os insights de uma publicação informam values[0].value. O exemplo pede alcance, visualizações e accounts_engaged na conta, e alcance, visualizações, curtidas, comentários, salvamentos e compartilhamentos em uma publicação ou Reel, que a referência da Meta lista para ambos. Uma métrica sem dados é omitida em vez de retornar 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}Como ler insights em Node.js?
As mesmas duas requisições em Node.js, cada uma retornando um objeto indexado pelo nome da métrica. Nenhuma envia o parâmetro breakdown: a Meta alerta que pedir um que a métrica não suporta faz a requisição falhar com um erro desconhecido, e que os dados de insights podem atrasar até 48 horas, então leia as publicações recentes de novo mais tarde.
// 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]));
}Como verificar um webhook em Python?
Com Flask, em duas rotas no mesmo caminho. O GET responde à requisição de verificação da Meta: quando hub.mode é subscribe e hub.verify_token confere, retorna hub.challenge como texto simples, e um 403 caso contrário. O POST calcula sha256= mais o HMAC-SHA256 do corpo bruto com o app secret, compara com X-Hub-Signature-256 em tempo constante e responde 200 antes de qualquer trabalho demorado começar.
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 "", 200Como verificar um webhook em Node.js?
Com o módulo http nativo, sem framework. O corpo é coletado como bytes brutos antes de qualquer análise, porque um corpo analisado e serializado novamente não confere mais com a assinatura que a Meta calculou. A Meta repete uma notificação que falhou por até 36 horas, então o handler também deve ignorar eventos que já processou.
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);Quais erros da Meta o código deve repetir?
Apenas os temporários, já que os demais devolvem a mesma resposta até que algo mude: o arquivo, a URL, uma permissão ou o estado da conta. As referências de erro da Meta indicam a ação para cada código que os auxiliares acima distinguem:
Como executar o mesmo código com as credenciais da easyCoexistence?
Não dá para rodar com o token da easyCoexistence: os tokens do Instagram nunca são entregues (termos da Meta), então get_social_credentials e o GET /api/v1/channels/:id?credentials=1 da Partner API retornam o ID e a base da API da conta, sem token. As mesmas tarefas rodam como ferramentas MCP, via Claude, ChatGPT ou outro cliente MCP, e os auxiliares acima rodam sem alterações com um token do seu próprio app da 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. ..."
}Como fazer as mesmas tarefas pelo conector MCP?
Pedindo ao assistente, ou chamando as ferramentas você mesmo. publish_instagram_post cria e publica o container, esperando enquanto um vídeo é processado, ou agenda com scheduled_at até 90 dias à frente; reply_to_comment responde publicamente, ou em privado por DM com private definido como true; get_social_insights repassa os nomes das métricas diretamente à Meta; e set_social_webhook_destination encaminha comentários, menções e DMs ao seu endpoint, assinados com 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" }
}
]Erros comuns
- Gerar hash do JSON já analisado. A Meta assina os bytes brutos, então o analisador de corpo JSON de um framework quebra a verificação de X-Hub-Signature-256; mantenha o corpo bruto e analise-o depois.
- Chamar media_publish de novo após um timeout sem verificar. Se o status_code do container indicar PUBLISHED, a publicação já está no ar.
- Ler o código 4 como limite de taxa sem o subcode. Com 2207051, significa que o Instagram suspeita de spam, e uma repetição repete a ação que acabou de ser restringida.
- Enviar o app secret ou o token a partir de código de navegador ou de app móvel. A Meta diz que requisições com o app secret devem ficar apenas em código de servidor.
De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, e os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Preciso de um SDK para chamar a API do Instagram?
Não. Cada chamada é uma requisição HTTPS com um token de acesso, então requests em Python ou fetch em Node.js bastam, como mostram os exemplos desta página.
Por que media_publish falha logo após a criação de um container de Reel?
O vídeo ainda está sendo processado: erro 9007 com subcode 2207027. Verifique o status_code do container uma vez por minuto e publique quando indicar FINISHED.
Qual versão da API o código deve usar?
Uma que a Meta ainda atenda: a v26.0 é a mais recente, e cada versão dura pelo menos dois anos. Uma chamada a uma versão removida é executada na versão anterior mais próxima ainda disponível.
Quanto custa a easyCoexistence para acesso à API de uma conta do Instagram?
Cada conta do Instagram é uma conexão: de US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, e os primeiros 3 dias grátis.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em