Das Wichtigste in Kürze
Die Instagram Graph API ermöglicht es Entwicklern, Instagram Business- und Creator-Konten programmatisch zu verwalten. Sie nutzt die Facebook Login OAuth 2.0-Authentifizierung, GraphQL-basierte Endpunkte für Inhaltsveröffentlichung, Insights, Kommentare und Nachrichten. Die Ratenbegrenzung liegt bei 200 Aufrufen pro Stunde und App. In diesem Leitfaden lernst du, wie du Authentifizierung einrichtest, Inhalte veröffentlichst, Insights abrufst, Kommentare verwaltest und Integrationsstrategien für die Produktion implementierst.
Einführung
Instagram zählt über 2 Milliarden monatlich aktive Nutzer, mit über 200 Millionen Unternehmen, die Business-Konten nutzen. Entwickler, die Social-Media-Tools, Analyseplattformen oder E-Commerce-Integrationen bauen, profitieren massiv von der Instagram Graph API.
Ohne Automatisierung verlieren Social Media Manager, die viele Konten betreuen, wöchentlich bis zu 30 Stunden für manuelles Posten, Kommentarbeantwortung und Analysen. Eine API-Integration automatisiert Posting, Moderation, Sentiment-Analyse und Performance-Reporting.
In diesem Guide erhältst du eine Schritt-für-Schritt-Anleitung zur Integration der Instagram Graph API. Du lernst Authentifizierung, Inhaltsveröffentlichung, Medien-Insights, Kommentarverwaltung, Webhook-Integration und Produktionsstrategien. Am Ende bist du in der Lage, eine produktionsreife Instagram-Integration zu erstellen.
💡 Apidog vereinfacht das Testen von API-Integrationen. Teste Instagram-Endpunkte, validiere OAuth-Flows, inspiziere API-Antworten und debugge Veröffentlichungsprobleme zentral. Importiere API-Spezifikationen, mocke Antworten und teile Testszenarien im Team.
Was ist die Instagram Graph API?
Die Instagram Graph API gibt dir programmatischen Zugriff auf Instagram Business- und Creator-Konten über die Facebook Graph API.
Typische Anwendungsfälle:
- Veröffentlichung von Inhalten (Fotos, Videos, Reels, Karussells)
- Medien-Insights und Analysen
- Kommentar- und Erwähnungsverwaltung
- Direktnachrichten (über Instagram Graph API + Messenger Platform)
- Hashtag- und Erwähnungsverfolgung
- Story-Verwaltung
- Shopping- und Produkt-Tags
Hauptmerkmale
| Merkmal | Beschreibung |
|---|---|
| Graph-basierte API | Node-basierter Ressourcenzugriff |
| OAuth 2.0 | Facebook Login Authentifizierung |
| Webhooks | Echtzeit-Benachrichtigungen für Kommentare, Erwähnungen |
| Ratenbegrenzung | 200 Aufrufe pro Stunde pro App |
| Inhaltsveröffentlichung | Fotos, Videos, Reels, Karussells |
| Insights | Engagement-, Reichweite-, Impressionen-Metriken |
| Moderation | Kommentare, Erwähnungen, Nachrichten verwalten |
Kontenanforderungen
| Kontotyp | API-Zugriff |
|---|---|
| Business-Konto | Voller API-Zugriff |
| Creator-Konto | Voller API-Zugriff |
| Persönliches Konto | Kein API-Zugriff (muss konvertiert werden) |
| Privates Konto | Begrenzte Insights |
Übersicht über die API-Architektur
Instagram nutzt die Facebook Graph API-Struktur:
https://graph.facebook.com/v18.0/
API-Versionen im Vergleich
| Version | Status | Enddatum | Anwendungsfall |
|---|---|---|---|
| v18.0 | Aktuell | März 2026 | Alle neuen Integrationen |
| v17.0 | Veraltet | Januar 2026 | Bestehende Integrationen |
| v16.0 | Eingestellt | Abgelaufen | Nicht verwenden |
Ziele immer auf die aktuelle stabile Version.
Erste Schritte: Authentifizierung einrichten
Schritt 1: Facebook-Entwicklerkonto erstellen
- Gehe zum Facebook Developers Portal
- Logge dich mit deinem Facebook-Konto ein
- Erstelle eine neue Facebook-App (Typ: Business)
- Füge das Instagram Graph API-Produkt hinzu
Schritt 2: Instagram Business-Konto verknüpfen
- Navigiere zu Facebook-Seiteneinstellungen > Instagram
- Klicke auf Konto verbinden
- Melde dich bei Instagram an und autorisiere die Verbindung
- Bestätige, dass das Business-Konto verknüpft ist
Hinweis: Persönliche Konten müssen erst in ein Business- oder Creator-Konto umgewandelt werden.
Schritt 3: Zugriffstoken abrufen
Erzeuge ein Benutzer-Zugriffstoken für OAuth:
const FB_APP_ID = process.env.FB_APP_ID;
const FB_APP_SECRET = process.env.FB_APP_SECRET;
const FB_REDIRECT_URI = process.env.FB_REDIRECT_URI;
// Authorisierungs-URL bauen
const getAuthUrl = (state) => {
const params = new URLSearchParams({
client_id: FB_APP_ID,
redirect_uri: FB_REDIRECT_URI,
scope: 'instagram_basic,instagram_content_publish,instagram_manage_comments,instagram_manage_insights,pages_read_engagement',
state: state
});
return `https://www.facebook.com/v18.0/dialog/oauth?${params.toString()}`;
};
Erforderliche Berechtigungen
| Berechtigung | Beschreibung |
|---|---|
instagram_basic |
Profilinfos, Medienliste |
instagram_content_publish |
Fotos, Videos, Karussells posten |
instagram_manage_comments |
Kommentare lesen/schreiben |
instagram_manage_insights |
Zugriff auf Analysedaten |
pages_read_engagement |
Seiten-Zugriff zum Veröffentlichen |
pages_manage_posts |
Auf verbundener Seite posten |
Schritt 4: Token gegen langlebiges Token tauschen
Kurzlebige Token (1h) gegen langlebige Token (60 Tage) tauschen:
const exchangeForLongLivedToken = async (shortLivedToken) => {
const response = await fetch(
`https://graph.facebook.com/v18.0/oauth/access_token?` +
`grant_type=fb_exchange_token&` +
`client_id=${FB_APP_ID}&` +
`client_secret=${FB_APP_SECRET}&` +
`fb_exchange_token=${shortLivedToken}`
);
const data = await response.json();
return data;
};
// Nutzung
const longLivedToken = await exchangeForLongLivedToken(shortLivedToken);
console.log(`Token expires: ${new Date(longLivedToken.expires_at * 1000)}`);
Schritt 5: Instagram Business-Konto-ID abrufen
Verknüpftes Instagram-Konto abfragen:
const getInstagramAccountId = async (pageId, accessToken) => {
const response = await fetch(
`https://graph.facebook.com/v18.0/${pageId}?fields=instagram_business_account&access_token=${accessToken}`
);
const data = await response.json();
return data.instagram_business_account.id;
};
// Nutzung
const igAccountId = await getInstagramAccountId('12345678', accessToken);
console.log(`Instagram Account ID: ${igAccountId}`);
Schritt 6: Authentifizierte API-Aufrufe tätigen
Wiederverwendbaren API-Client bauen:
const IG_BASE_URL = 'https://graph.facebook.com/v18.0';
const instagramRequest = async (endpoint, params = {}) => {
const url = new URL(`${IG_BASE_URL}${endpoint}`);
url.searchParams.append('access_token', process.env.INSTAGRAM_ACCESS_TOKEN);
Object.entries(params).forEach(([key, value]) => {
url.searchParams.append(key, value);
});
const response = await fetch(url.toString());
if (!response.ok) {
const error = await response.json();
throw new Error(`Instagram API Error: ${error.error.message}`);
}
return response.json();
};
// Nutzung
const account = await instagramRequest(`/me`);
console.log(`Instagram Account: ${account.username}`);
Inhaltsveröffentlichung
Ein Foto veröffentlichen
So postest du ein Foto per API:
const publishPhoto = async (igAccountId, photoData) => {
// Schritt 1: Media-Container erstellen
const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
method: 'POST',
image_url: photoData.imageUrl,
caption: photoData.caption,
location_id: photoData.locationId, // Optional
is_carousel_item: 'false'
});
const creationId = containerResponse.id;
// Schritt 2: Media veröffentlichen
const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
method: 'POST',
creation_id: creationId
});
return publishResponse;
};
// Nutzung
const post = await publishPhoto({
igAccountId: '17841400000000000',
imageUrl: 'https://example.com/image.jpg',
caption: 'Excited to announce our new product! 🚀 #launch #innovation',
locationId: '123456789' // Optional
});
console.log(`Published media ID: ${post.id}`);
Ein Video veröffentlichen
So veröffentlichst du ein Video (inkl. Polling auf Verarbeitung):
const publishVideo = async (igAccountId, videoData) => {
// Schritt 1: Media-Container erstellen
const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
method: 'POST',
video_url: videoData.videoUrl,
cover_url: videoData.coverUrl, // Optional
caption: videoData.caption,
media_type: 'REELS', // oder 'VIDEO'
share_to_feed: 'true' // Für Reels
});
const creationId = containerResponse.id;
// Video-Verarbeitung abwarten
await waitForVideoProcessing(creationId);
// Schritt 2: Media veröffentlichen
const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
method: 'POST',
creation_id: creationId
});
return publishResponse;
};
const waitForVideoProcessing = async (creationId, maxAttempts = 30) => {
for (let i = 0; i < maxAttempts; i++) {
const status = await instagramRequest(`/${creationId}`);
if (status.status_code === 'FINISHED') {
return true;
} else if (status.status_code === 'EXPIRED') {
throw new Error('Video processing expired');
}
await new Promise(resolve => setTimeout(resolve, 2000));
}
throw new Error('Video processing timeout');
};
Ein Karussell veröffentlichen (mehrere Bilder/Videos)
Mehrere Medien in einem Post:
const publishCarousel = async (igAccountId, carouselData) => {
const children = [];
// Schritt 1: Einzelne Carousel-Items anlegen
for (const item of carouselData.items) {
const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
method: 'POST',
[item.type === 'video' ? 'video_url' : 'image_url']: item.url,
caption: item.caption || '',
is_carousel_item: 'true'
});
children.push(containerResponse.id);
}
// Schritt 2: Carousel-Container mit Children erstellen
const carouselContainerResponse = await instagramRequest(`/${igAccountId}/media`, {
method: 'POST',
media_type: 'CAROUSEL',
children: children.join(','),
caption: carouselData.caption
});
const creationId = carouselContainerResponse.id;
// Schritt 3: Carousel veröffentlichen
const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
method: 'POST',
creation_id: creationId
});
return publishResponse;
};
// Nutzung
const carousel = await publishCarousel('17841400000000000', {
caption: 'Product showcase 2026',
items: [
{ type: 'image', url: 'https://example.com/img1.jpg', caption: 'Product 1' },
{ type: 'image', url: 'https://example.com/img2.jpg', caption: 'Product 2' },
{ type: 'video', url: 'https://example.com/vid1.mp4', caption: 'Demo' }
]
});
Medientypen
| Medientyp | Parameter | Anwendungsfall |
|---|---|---|
IMAGE |
image_url, caption | Foto-Beiträge |
VIDEO |
video_url, cover_url, caption | Video-Beiträge |
REELS |
video_url, cover_url, caption, share_to_feed | Reels |
CAROUSEL |
children (Array), caption | Mehrere Medien |
Medien und Insights abrufen
Benutzermedien abrufen
So listest du alle Medien eines Kontos:
const getUserMedia = async (igAccountId, limit = 25) => {
const response = await instagramRequest(`/${igAccountId}/media`, {
fields: 'id,caption,media_type,media_url,permalink,timestamp,like_count,comments_count',
limit: limit.toString()
});
return response;
};
// Nutzung
const media = await getUserMedia('17841400000000000');
media.data.forEach(item => {
console.log(`${item.media_type}: ${item.caption}`);
console.log(`Likes: ${item.like_count}, Comments: ${item.comments_count}`);
console.log(`URL: ${item.permalink}`);
});
Medien-Insights abrufen
Analysiere ein bestimmtes Medium:
const getMediaInsights = async (mediaId) => {
const response = await instagramRequest(`/${mediaId}/insights`, {
fields: 'impressions,reach,engagement,saved,video_views,profile_visits,follows'
});
return response;
};
// Nutzung
const insights = await getMediaInsights('17890000000000000');
insights.data.forEach(metric => {
console.log(`${metric.name}: ${metric.values[0].value}`);
});
Verfügbare Insights-Metriken
| Metrik | Beschreibung | Medientypen |
|---|---|---|
impressions |
Gesamtzahl der Aufrufe | Alle |
reach |
Einzigartige erreichte Konten | Alle |
engagement |
Likes + Kommentare + Speicherungen | Alle |
saved |
Anzahl der Speicherungen | Alle |
video_views |
Video-Aufrufe (3+ Sekunden) | Video, Reels |
plays |
Gesamtzahl der Video-Wiedergaben | Video, Reels |
profile_visits |
Profilbesuche durch Beitrag | Alle |
follows |
Follower durch Beitrag | Alle |
comments |
Anzahl der Kommentare | Alle |
like_count |
Anzahl der Likes | Alle |
Konto-Insights abrufen
Aggregierte Metriken für das Konto:
const getAccountInsights = async (igAccountId, metricNames, since = null, until = null) => {
const params = {
metric: metricNames.join(','),
period: 'day'
};
if (since) params.since = since;
if (until) params.until = until;
const response = await instagramRequest(`/${igAccountId}/insights`, params);
return response;
};
// Nutzung (letzte 30 Tage)
const accountInsights = await getAccountInsights(
'17841400000000000',
['impressions', 'reach', 'profile_views', 'email_contacts', 'website_clicks'],
'2026-02-23',
'2026-03-25'
);
accountInsights.data.forEach(metric => {
console.log(`${metric.name}:`);
metric.values.forEach(value => {
console.log(` ${value.end_time}: ${value.value}`);
});
});
Metriken auf Kontoebene
| Metrik | Beschreibung |
|---|---|
impressions |
Profil- + Inhaltsansichten gesamt |
reach |
Einzigartige erreichte Konten |
profile_views |
Profilbesuche |
website_clicks |
Klicks auf Link in Bio |
email_contacts |
Taps auf E-Mail-Button |
phone_call_clicks |
Taps auf Telefon-Button |
text_message_clicks |
Taps auf SMS-Button |
get_directions_clicks |
Klicks auf Adresse |
follower_count |
Anzahl der Follower |
audience_city |
Städte der Follower |
audience_country |
Länder der Follower |
audience_gender_age |
Demografie der Follower |
Kommentarverwaltung
Kommentare abrufen
Kommentare zu Medienlisten:
const getMediaComments = async (mediaId, limit = 50) => {
const response = await instagramRequest(`/${mediaId}/comments`, {
fields: 'id,text,timestamp,username,hidden',
limit: limit.toString()
});
return response;
};
// Nutzung
const comments = await getMediaComments('17890000000000000');
comments.data.forEach(comment => {
console.log(`@${comment.username}: ${comment.text}`);
console.log(`Hidden: ${comment.hidden}`);
});
Auf Kommentare antworten
Antwort posten:
const replyToComment = async (mediaId, commentId, replyText) => {
const response = await instagramRequest(`/${mediaId}/comments`, {
method: 'POST',
response_to: commentId,
message: replyText
});
return response;
};
// Nutzung
const reply = await replyToComment(
'17890000000000000',
'17900000000000000',
'Thank you for your interest! Check your DM for details.'
);
console.log(`Reply posted: ${reply.id}`);
Kommentare ausblenden
Unerwünschte Kommentare verstecken:
const hideComment = async (commentId) => {
const response = await instagramRequest(`/${commentId}`, {
method: 'POST',
hide: 'true'
});
return response;
};
// Nutzung
await hideComment('17900000000000000');
console.log('Comment hidden');
Kommentare löschen
Spam/irrelevante Kommentare entfernen:
const deleteComment = async (commentId) => {
await instagramRequest(`/${commentId}`, {
method: 'DELETE'
});
console.log('Comment deleted');
};
Webhooks
Webhooks konfigurieren
Echtzeit-Benachrichtigungen abonnieren:
const subscribeToWebhooks = async (appId, pageId, accessToken) => {
// Instagram-Events abonnieren
const response = await fetch(
`https://graph.facebook.com/v18.0/${appId}/subscriptions`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
object: 'instagram',
callback_url: 'https://myapp.com/webhooks/instagram',
verify_token: process.env.WEBHOOK_VERIFY_TOKEN,
access_token: accessToken,
fields: ['comments', 'mentions', 'message_reactions']
})
}
);
return response.json();
};
Webhooks verarbeiten
Webhook-Handler mit Express.js:
const express = require('express');
const app = express();
// Webhook-Verifizierung
app.get('/webhooks/instagram', (req, res) => {
const mode = req.query['hub.mode'];
const token = req.query['hub.verify_token'];
const challenge = req.query['hub.challenge'];
if (mode === 'subscribe' && token === process.env.WEBHOOK_VERIFY_TOKEN) {
console.log('Webhook verified');
res.status(200).send(challenge);
} else {
res.status(403).send('Verification failed');
}
});
// Ereignisse verarbeiten
app.post('/webhooks/instagram', express.json(), async (req, res) => {
const body = req.body;
if (body.object !== 'instagram') {
return res.status(404).send('Not found');
}
for (const entry of body.entry) {
const igId = entry.id;
const changes = entry.changes;
for (const change of changes) {
switch (change.field) {
case 'comments':
await handleNewComment(change.value);
break;
case 'mentions':
await handleMention(change.value);
break;
case 'message_reactions':
await handleReaction(change.value);
break;
}
}
}
res.status(200).send('OK');
});
async function handleNewComment(data) {
console.log(`New comment on media ${data.media_id}`);
console.log(`From: ${data.from_id}`);
console.log(`Text: ${data.text}`);
// Automatische Moderation
if (isSpam(data.text)) {
await hideComment(data.id);
}
}
Webhook-Felder
| Feld | Auslöser |
|---|---|
comments |
Neuer Kommentar/Antwort |
mentions |
Benutzer erwähnt Konto |
message_reactions |
Reaktion auf Story |
story_status |
Story-Antwort/Ansicht |
Ratenbegrenzung
Ratenbegrenzungen verstehen
Die Instagram Graph API limitiert:
- 200 Aufrufe pro Stunde pro App (geteilt auf alle User)
- Business Discovery: 200 Aufrufe/Stunde pro User
- Inhaltsveröffentlichung: Aktionstypabhängig
Überlimitierte Anfragen führen zu HTTP 400 mit Subcode 613.
Best Practices für Ratenbegrenzungen
- Antworten cachen – Wiederholte, unveränderte Daten vermeiden
- Anfragen bündeln – Feldexpansion nutzen
- Webhooks verwenden – Echtzeit-Updates statt Polling
- Backoff implementieren – Exponentiellen Backoff bei 429-Fehlern
const makeRateLimitedRequest = async (endpoint, params = {}, maxRetries = 3) => {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const response = await instagramRequest(endpoint, params);
return response;
} catch (error) {
if (error.message.includes('429') && attempt < maxRetries) {
const delay = Math.pow(2, attempt) * 1000;
console.log(`Rate limited. Retrying in ${delay}ms...`);
await new Promise(resolve => setTimeout(resolve, delay));
} else {
throw error;
}
}
}
};
Häufige Probleme beheben
Problem: OAuth-Token abgelaufen
Symptome: "Ungültiger OAuth-Zugriffstoken".
Lösungen:
- Token-Refresh vor Ablauf der 60 Tage implementieren
- Ablaufdatum speichern und rechtzeitig benachrichtigen
- Benutzer erneut authentifizieren, sobald das Token abläuft
Problem: Medienveröffentlichung schlägt fehl
Symptome: Fehler beim Veröffentlichen.
Lösungen:
- Bild-URL muss öffentlich erreichbar sein
- Bildformat (JPEG, PNG) und Größe (<8 MB) prüfen
- Video: MP4, <1 GB, <90 Sekunden
- Video-Verarbeitung abwarten, bevor veröffentlicht wird
Problem: Insights nicht verfügbar
Symptome: Insights API liefert leere Daten.
Lösungen:
- Konto muss Business/Creator sein
- 24–48 Stunden warten, bis Daten gefüllt sind
- Kontenaktivität sicherstellen
Checkliste für die Produktionsbereitstellung
Vor dem Go-Live:
- [ ] Testkonten zu Business/Creator umstellen
- [ ] OAuth 2.0 mit langlebigen Tokens nutzen
- [ ] Tokens sicher und verschlüsselt speichern
- [ ] Automatischen Token-Refresh einbauen
- [ ] Webhook-Endpunkte per HTTPS ausliefern
- [ ] Ratenbegrenzung und Anfragewarteschlange implementieren
- [ ] Fehlerbehandlung umfassend einbauen
- [ ] Logging für alle API-Aufrufe aktivieren
- [ ] Inhaltsmoderations-Workflows erstellen
- [ ] Mit verschiedenen Kontotypen testen
Anwendungsfälle aus der Praxis
Tool zur Social-Media-Planung
Herausforderung: Manuelles Posten über 50+ Kundenkonten
Lösung: Geplante Veröffentlichung via Instagram API
Ergebnis: 80% Zeitersparnis, konsistenter Redaktionsplan
Implementierung:
- Drag-and-Drop-Inhaltskalender
- Automatische Foto/Video/Karussell-Veröffentlichung
- Hashtag-Suggestion basierend auf Content
Kundendienst-Automatisierung
Herausforderung: Langsame Reaktion auf Kundenfragen
Lösung: Automatische Beantwortung über Webhook
Ergebnis: Antwortzeit 5 Minuten, 90% Zufriedenheit
Implementierung:
- Stichworterkennung (Preis, Verfügbarkeit, Versand)
- Automatische Antwort mit Produktlink
- Komplexe Anfragen an Menschen eskalieren
Fazit
Die Instagram Graph API bietet umfassenden Zugriff für Business- und Creator-Konten. Wesentliche Punkte für Entwickler:
- Facebook Login OAuth 2.0-Authentifizierung, langlebige Tokens (60 Tage)
- Inhaltsveröffentlichung: Fotos, Videos, Reels, Karussells
- Insights API: Engagement-, Reichweiten-, Demografiedaten
- Webhooks: Echtzeitüberwachung von Kommentaren, Erwähnungen
- Ratenbegrenzung: 200 Aufrufe/Stunde/App – Rate-Limiting beachten
- Apidog optimiert API-Testing und Teamwork
FAQ-Bereich
Wie erhalte ich Zugang zur Instagram API?
Erstelle ein Facebook-Entwicklerkonto, eine Business-App, füge das Instagram Graph API-Produkt hinzu und authentifiziere dich über Facebook Login mit den nötigen Berechtigungen.
Kann ich automatisch auf Instagram posten?
Ja, über die Content Publishing API kannst du Fotos, Videos, Reels und Karussells auf Business- und Creator-Konten veröffentlichen.
Welche Arten von Instagram-Konten unterstützen die API?
Nur Business- und Creator-Konten haben vollen API-Zugriff. Persönliche Konten sind ausgeschlossen.
Wie rufe ich Kommentare von Instagram ab?
Nutze den Kommentare-Endpunkt (/{media-id}/comments) für Medienkommentare. Webhooks liefern Echtzeit-Benachrichtigungen.
Was sind die Ratenbegrenzungen von Instagram?
200 Aufrufe pro Stunde pro App. Einzelne Endpunkte können weitere Limits pro Nutzer haben.
Kann ich Stories über die API veröffentlichen?
Ja, Stories werden mit dem gleichen Publishing-Flow erstellt wie normale Feed-Posts.
Wie greife ich auf Instagram Insights zu?
Fordere instagram_manage_insights beim OAuth-Prozess an. Verwende dann den Insights-Endpunkt für Medien/Konten.
Kann ich automatisch auf Kommentare antworten?
Ja, über die Kommentare-API kannst du programmatisch auf Kommentare antworten. Viele Unternehmen automatisieren so den Kundendialog.
Top comments (0)