Channel Connection API #

Dieser Leitfaden zeigt Ihnen, wie Sie Messaging-Kanäle über die API mit einem Konto verbinden. Er richtet sich an Entwickler, die eine Integration oder einen Wrapper erstellen, und konzentriert sich daher auf die genauen Anfragen, die Reihenfolge ihrer Ausführung und die erhaltenen Antworten.

Es gibt ein Muster, das Sie vorab verstehen müssen, da es auf fast jeden Kanal hier zutrifft.

Das Verbinden-dann-Abfragen-Muster (Connect-then-poll) #

Die meisten Kanäle können nicht mit einem einzigen API-Aufruf verbunden werden. Das Verbinden von WhatsApp, Instagram oder Messenger erfordert, dass sich der Kontoinhaber bei seinem jeweiligen Anbieter anmeldet und den Zugriff genehmigt. Es gibt keinen Headless-Pfad (vollautomatisch) für diese Genehmigung – eine echte Person muss eine URL in einem Browser öffnen oder einen QR-Code mit ihrem Telefon scannen.

Der Ablauf ist daher immer:

1. Starten Sie die Verbindung mit einem POST. Die Antwort liefert Ihnen entweder eine URL zum Öffnen oder einen QR-Code zur Anzeige.
2. Übergeben Sie dies an den Endbenutzer – öffnen Sie die URL in dessen Browser oder zeigen Sie den QR-Code auf dem Bildschirm an, damit er ihn scannen kann.
3. Fragen Sie den Status-Endpunkt mit GET in kurzen Abständen (alle paar Sekunden) ab, bis der Status den verbundenen Zustand erreicht.

Die Aufgabe Ihrer Integration ist es, diese Schleife zu steuern: Zeigen Sie die URL oder den QR-Code an und fragen Sie dann ab, bis der Vorgang abgeschlossen ist. Planen Sie Ihre Benutzeroberfläche um den Abfragevorgang herum – ein Lade-Spinner mit einer Nachricht wie „Warten auf Abschluss in Ihrem Browser“ funktioniert gut.

Instagram + Messenger (Meta) #

Instagram und Messenger werden in einem gemeinsamen Ablauf verbunden, da beide über eine Facebook-Seite laufen. Der Kontoinhaber autorisiert den Zugriff über Facebook, Sie rufen die Liste der von ihm verwalteten Seiten ab und wählen aus, welche Seite verbunden werden soll.

Schritt 1 - Starten der Instagram + Messenger-Verbindung #

POST /channels/meta/connect

Dies gibt eine Zustimmungs-URL zurück. Bei dieser Anfrage werden keine Anmeldedaten gesendet – die Verbindung wird vollständig im Browser autorisiert.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/connect", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Open data.oauth_url in the end user's browser.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Open data["oauth_url"] in the end user's browser.

Antwort

{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "connect_url": "https://api.youraiconnector.com/v1/channels/meta/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Öffnen Sie oauth_url im Browser des Endbenutzers, damit dieser sich bei Facebook anmelden und den Zugriff genehmigen kann. Der Verbindungsversuch läuft nach expires_at ab (ca. 30 Minuten) – falls er abläuft, beginnen Sie von vorn. Behandeln Sie state_token als kurzlebiges Geheimnis und protokollieren Sie es nicht.

Einfachste Option für Instagram + Messenger: übergeben Sie connect_url #

Die Antwort enthält auch eine fertige connect_url: eine gehostete Seite, die den gesamten Ablauf für den Kontoinhaber ausführt. Er öffnet sie, meldet sich bei Facebook an, und wenn er mehr als eine Seite hat, wird die Liste angezeigt, aus der er die zu verbindende Seite auswählen kann – danach meldet sie den Erfolg selbstständig. Geben Sie diesen Link an den Kontoinhaber weiter, anstatt oauth_url selbst zu öffnen, eine Seitenauswahl zu erstellen und Abfragen durchzuführen. Der Link funktioniert für etwa 30 Minuten (connect_url_expires_at); wenn er abläuft, starten Sie eine neue Verbindung. Die folgenden manuellen Schritte sind für Integrationen gedacht, die den Ablauf steuern und die Seitenauswahl selbst rendern möchten.

Schritt 2 – Status abfragen, bis die Seiten geladen sind #

GET /channels/meta/status

Nachdem der Benutzer die Facebook-Anmeldung abgeschlossen hat, fragen Sie diesen Endpunkt alle paar Sekunden ab. Das Feld status durchläuft diese Schritte:

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/status", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Poll until data.status === "pages_loaded".

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "pages_loaded".

Antwort (sobald die Seiten geladen wurden)

{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1234567890",
      "name": "My Business Page",
      "category": "Local business",
      "instagram_business_account": {
        "id": "17890000000000000",
        "username": "mybusiness"
      }
    }
  ],
  "selected_page": null
}

Schritt 3 – Seiten auflisten (optional) #

Wenn Sie die Seitenliste separat abrufen möchten (z. B. um eine Auswahlmöglichkeit anzuzeigen), verwenden Sie:

GET /channels/meta/pages

curl "https://api.youraiconnector.com/v1/channels/meta/pages" \
  -H "X-API-Key: YOUR_API_KEY"

Dies gibt dasselbe pages-Array zurück wie der Status-Endpunkt. (Der status-Endpunkt enthält bereits die Seiten, daher ist dieser Aufruf lediglich eine Komfortfunktion.)

Schritt 4 – Die zu verbindende Seite auswählen #

POST /channels/meta/select-page

Senden Sie die page_id der Seite, die der Benutzer ausgewählt hat. Das mit dieser Seite verknüpfte Instagram-Konto wird automatisch verbunden; Sie benötigen das instagram-Objekt nur, wenn Sie überschreiben möchten, welches Instagram-Konto verwendet werden soll.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/select-page" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page_id": "1234567890" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/select-page", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ page_id: "1234567890" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/select-page",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"page_id": "1234567890"},
)
data = res.json()

Antwort

{
  "success": true,
  "page_id": "1234567890",
  "instagram_business_account_id": "17890000000000000"
}

Der Kanal ist nun verbunden. Ein nachfolgender GET /channels/meta/status meldet status: "connected".

Beiträge der verbundenen Seite auflisten #

GET /channels/meta/posts?platform=instagram

Gibt die aktuellen Beiträge der von Ihnen verbundenen Seite zurück – Instagram-Medien oder Facebook-Beiträge. Dies ist die Grundlage, aus der Sie eine Auswahl erstellen, wenn Sie einen Einstiegspunkt einrichten, der auf Kommentare zu einem bestimmten Beitrag reagiert.

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/posts?platform=instagram&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "connected": true,
  "platform": "instagram",
  "posts": [
    {
      "id": "17900000000000000",
      "caption": "New spring menu is live",
      "thumbnailUrl": "https://scontent.cdninstagram.com/...",
      "permalink": "https://www.instagram.com/p/Cxxxxxxxxxx/",
      "createdAt": "2026-05-02T09:12:00.000Z",
      "mediaType": "REELS"
    }
  ],
  "nextCursor": "QVFIUkxxxxxxxx"
}

mediaType ist das eigene Label von Instagram (REELS, FEED, STORY oder das Format – IMAGE, VIDEO, CAROUSEL_ALBUM); für Facebook ist es immer POST. nextCursor ist null auf der letzten Seite.

Wenn nichts aufgelistet werden kann, gibt der Aufruf dennoch 200 mit connected: false und einem leeren posts-Array zurück, sowie einen reason, der den Grund angibt:

Trennen der Instagram + Messenger-Verbindung #

DELETE /channels/meta

curl -X DELETE "https://api.youraiconnector.com/v1/channels/meta" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "disconnected": true }

Dies stoppt das eingehende Routing für Instagram und Messenger. Es ist idempotent – der Aufruf, wenn nichts verbunden ist, ist weiterhin erfolgreich.

WhatsApp Business #

Dies verbindet eine offizielle WhatsApp Business-Nummer. Die Nummer muss bereits im Konto existieren, bevor Sie die Verbindung aufrufen. Wie bei Meta autorisiert der Kontoinhaber dies in seinem Browser, danach fragen Sie den Status ab, bis die Nummer ONLINE meldet.

Schritt 1 - Starten der WhatsApp Business-Verbindung #

POST /channels/whatsapp/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155551234" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155551234" }),
});
const data = await res.json();
// Open data.oauth_url in the account holder's browser.

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155551234"},
)
data = res.json()
# Open data["oauth_url"] in the account holder's browser.

Antwort

{
  "success": true,
  "status": "pending",
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Öffnen Sie oauth_url im Browser des Kontoinhabers, um die Autorisierung durchzuführen. Sobald diese genehmigt wurde, wird die Registrierung im Hintergrund abgeschlossen.

Schritt 2 - Status abfragen, bis ONLINE #

GET /channels/whatsapp/connect/{phoneNumber}/status

Fragen Sie dies ab, bis status den Wert ONLINE hat.

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp/connect/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp/connect/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp/connect/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Antwort

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Das Feld status kann folgende Werte annehmen:

live: true bedeutet, dass der Status in Echtzeit beim Anbieter überprüft wurde; false bedeutet, dass er aus dem letzten zwischengespeicherten Zustand stammt.

Trennen einer WhatsApp Business-Nummer #

DELETE /channels/whatsapp/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "phone_number": "+14155551234", "disconnected": true }

Die Nummer selbst bleibt im Konto erhalten, sodass Sie sie später wieder verbinden können.

WhatsApp Web #

WhatsApp Web verknüpft eine reguläre WhatsApp-Nummer durch Scannen eines QR-Codes, genau wie beim Verknüpfen eines Geräts in der WhatsApp-App. Der Ablauf ist: Sitzung starten, QR-Code abrufen und anzeigen, dann abfragen, bis der Status connected lautet.

Schritt 1 - Starten einer WhatsApp Web-Kopplungssitzung #

POST /channels/whatsapp-web/connections

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp-web/connections", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+15551230000" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+15551230000"},
)
data = res.json()

Antwort

{
  "success": true,
  "phone_number": "+15551230000",
  "session_id": "session-id",
  "status": "qr_pending",
  "connect_url": "https://api.youraiconnector.com/v1/channels/whatsapp-web/connect?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "poll_qr_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/qr",
  "poll_status_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/status"
}

Einfachste Option für WhatsApp Web: übergeben Sie connect_url #

Die Antwort enthält eine fertige connect_url: eine gehostete Seite, die den QR-Code anzeigt, ihn bei der Rotation automatisch aktualisiert und zu einer Erfolgsmeldung wechselt, sobald die Nummer verknüpft ist. Geben Sie diesen Link einfach an den Kontoinhaber weiter (öffnen Sie ihn in einem Browser, senden Sie ihn oder zeigen Sie ihn als QR-Code/Schaltfläche an) und lassen Sie ihn diesen mit WhatsApp scannen – Sie müssen den QR-Code nicht selbst abrufen oder irgendetwas abfragen. Der Link funktioniert etwa 30 Minuten lang (connect_url_expires_at); falls er abläuft, bevor der Vorgang abgeschlossen ist, starten Sie eine neue Verbindung, um einen neuen Link zu erhalten.

Dies ist der empfohlene Weg, wenn eine Person einen Link öffnen kann. Die manuellen Schritte unten (den QR-Code selbst abrufen, den Status abfragen) sind für Integrationen gedacht, die den QR-Code stattdessen in ihrer eigenen Benutzeroberfläche darstellen möchten.

Die Antwort liefert Ihnen auch den genauen poll_qr_path und poll_status_path zur Verwendung, sodass Sie diese nicht selbst erstellen müssen.

Schritt 2 - QR-Code abrufen und anzeigen #

GET /channels/whatsapp-web/connections/{phoneNumber}/qr

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/qr`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Render data.qr_data_url as an <img src> for the user to scan.

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/qr",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Render data["qr_data_url"] for the user to scan.

Antwort

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@raw-qr-payload-string...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-06-10T12:05:00.000Z"
}

Stellen Sie den QR-Code für den Benutzer bereit, damit dieser ihn mit seinem Telefon scannen kann (WhatsApp > Verknüpfte Geräte > Gerät hinzufügen):

• qr_data_url ist ein sofort einsatzbereites Bild – fügen Sie es direkt in ein <img src> ein.
• qr_code ist die Roh-Payload, falls Sie das Bild lieber selbst generieren möchten.

Der QR-Code ist nur kurz gültig. Wenn Sie dies direkt nach dem Starten der Sitzung aufrufen, erhalten Sie möglicherweise einen 404 mit “QR code not available yet” – warten Sie einfach einen Moment und versuchen Sie es erneut. Wenn Sie einen 410 (“QR code expired”) erhalten, starten Sie die Verbindung neu, um einen neuen Code zu erhalten.

Schritt 3 - Status abfragen, bis die Verbindung hergestellt ist #

GET /channels/whatsapp-web/connections/{phoneNumber}/status

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "connected" (or "open").

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "connected" (or "open").

Antwort

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "connected",
  "has_qr": false,
  "qr_expires_at": null,
  "last_activity": null,
  "message_count": null,
  "proxy": null,
  "live": true
}

Trennen einer WhatsApp Web-Sitzung #

DELETE /channels/whatsapp-web/connections/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "phone_number": "+15551230000", "status": "removed" }

Dies hebt die Verknüpfung des Geräts auf und entfernt die Verbindung. Es bereinigt immer den lokalen Status und ist daher idempotent, selbst wenn die zugrunde liegende Sitzung bereits beendet war.

Telegram #

Verfügbarkeit: Telegram lässt sich wie jeder andere Kanal verbinden und steht jedem Konto offen — Sie müssen es nicht für sich freischalten lassen. Die unten aufgeführten Telegram-Endpunkte können dennoch 403 zurückgeben, wenn Telegram nicht im Plan des Kontos enthalten ist; in diesem Fall lautet die Fehlermeldung "This channel is not included in your current plan. Upgrade to unlock it.".

Telegram verbindet ein persönliches Konto über die Telefonnummer und einen einmaligen Anmeldecode (sowie ein Zwei-Faktor-Passwort, falls für das Konto eines festgelegt wurde). Der Ablauf ist: Sitzung starten, Code übermitteln, optional Passwort übermitteln und dann den Status bestätigen.

Schritt 1 - Starten einer Telegram-Verbindungssitzung #

POST /channels/telegram/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/telegram/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155550100" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/telegram/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155550100"},
)
data = res.json()

Antwort

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "code_required",
  "session_id": "session-id",
  "connect_url": "https://api.youraiconnector.com/v1/channels/telegram/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

Im code-Modus erhält das Konto einen Anmeldecode in Telegram und status ist code_required. (Im qr-Modus enthält die Antwort zusätzlich login_token und qr_url zum Scannen, und status ist qr_required.)

Einfachste Option für Telegram: übergeben Sie connect_url #

Die Antwort enthält eine fertige connect_url: eine gehostete Seite, die die Verbindung selbstständig abschließt. Im code-Modus gibt der Kontoinhaber den Anmeldecode ein – sowie ein Passwort für die zweistufige Verifizierung, falls das Konto über ein solches verfügt. Im qr-Modus zeigt die Seite einen QR-Code an, der sich automatisch aktualisiert, damit er mit der Telegram-App gescannt werden kann. In beiden Fällen wird der Erfolg automatisch gemeldet, sodass Sie diesen Link einfach an den Kontoinhaber weitergeben können, anstatt eine eigene Benutzeroberfläche zu erstellen und Abfragen (Polling) durchzuführen. Der Link ist etwa 30 Minuten lang gültig (connect_url_expires_at); wenn er abläuft, starten Sie eine neue Verbindung, um einen neuen Link zu erhalten.

Die folgenden manuellen Schritte (Code selbst erfassen, übermitteln, Status abfragen; oder qr_url rendern und abfragen) sind für Integrationen gedacht, die die Benutzeroberfläche selbst rendern möchten.

Schritt 2 - Anmeldecode übermitteln #

POST /channels/telegram/connect/{phoneNumber}/verify-code

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-code" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "12345" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-code`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ code: "12345" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-code",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"code": "12345"},
)
data = res.json()

Antwort

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Wenn status den Wert connected hat, sind Sie fertig. Wenn für das Konto die Zwei-Faktor-Authentifizierung aktiviert ist, ist status stattdessen password_required – fahren Sie mit Schritt 3 fort.

Schritt 3 - Zwei-Faktor-Passwort übermitteln (nur bei Bedarf) #

POST /channels/telegram/connect/{phoneNumber}/verify-password

Rufen Sie dies nur auf, wenn Schritt 2 password_required zurückgegeben hat.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-password" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "the-2fa-password" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-password`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ password: "the-2fa-password" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-password",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"password": "the-2fa-password"},
)
data = res.json()

Antwort

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Telegram-Status prüfen #

GET /channels/telegram/connect/{phoneNumber}/status

curl "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/status" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "live": true
}

status kann connected, code_required, password_required, initializing, disconnected, not_initialized oder error sein.

Trennen von Telegram #

DELETE /channels/telegram/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/telegram/+14155550100" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "phone_number": "+14155550100", "status": "removed" }

Idempotent – wiederholte Aufrufe sind erfolgreich.

Instagram (privates Konto) #

Beta-Version mit begrenzter Verfügbarkeit, pro Konto aktiviert. Dies verbindet ein privates Instagram-Konto durch Anmeldung mit Benutzername und Passwort (nicht über die offizielle Business-API). Wenn das Konto nicht für die Beta-Version freigeschaltet ist, gibt der Verbindungsaufruf einen Berechtigungsfehler zurück.

Da dies die eigenen Instagram-Anmeldedaten des Kontoinhabers erfordert, ist der einfachste Weg, ihm die gehostete connect_url zu geben und ihn seine Anmeldedaten dort eingeben zu lassen – Ihre Integration verarbeitet das Passwort zu keinem Zeitpunkt.

Schritt 1 - Starten einer Instagram-Verbindung (persönlich) #

POST /channels/instagram-private/connect

Senden Sie die Instagram username und password.

Antwort

{
  "success": true,
  "status": "connected",
  "connect_url": "https://api.youraiconnector.com/v1/channels/instagram-private/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

Wenn das Konto eine Zwei-Faktor-Authentifizierung hat oder Instagram einen Checkpoint anzeigt, wird status als two_factor_required oder challenge_required zurückgegeben – senden Sie den Code an /connect/{id}/verify-2fa oder /connect/{id}/verify-challenge unten und fragen Sie dann /connect/{id}/status ab, bis connected erscheint. {id} ist der normalisierte Instagram-Benutzername, der als account_id/username in der obigen Antwort zurückgegeben wird – verwenden Sie ihn bei jedem der folgenden Schritte.

Schritt 2 – Zwei-Faktor-Code übermitteln (falls angefordert) #

POST /channels/instagram-private/connect/{id}/verify-2fa

Rufen Sie dies nur auf, wenn Schritt 1 (oder Schritt 3) two_factor_required zurückgegeben hat.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-2fa" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Antwort

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand"
}

status kann als connected (erledigt), two_factor_required (falscher Code, versuchen Sie es erneut) oder challenge_required (Instagram verlangt zusätzlich einen Checkpoint-Code – gehen Sie zu Schritt 3) zurückgegeben werden.

Schritt 3 – Checkpoint-Bestätigungscode übermitteln (falls angefordert) #

POST /channels/instagram-private/connect/{id}/verify-challenge

Rufen Sie dies nur auf, wenn ein vorheriger Schritt challenge_required zurückgegeben hat. Gleiches Anfrage- und Antwortformat wie bei Schritt 2 oben.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-challenge" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Status von Instagram (persönlich) prüfen #

GET /channels/instagram-private/connect/{id}/status

Fragen Sie dies ab, bis status den Wert connected hat oder ein endgültiger Fehler gemeldet wird.

curl "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/status" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand",
  "live": true
}

status kann connected, two_factor_required, challenge_required, initializing, disconnected, not_initialized oder error sein. live: true bedeutet, dass dies live vom Verbindungs-Worker gelesen wurde und kein zwischengespeicherter Wert ist.

Einfachste Option für Instagram (persönlich): übergeben Sie connect_url #

Die Antwort enthält eine connect_url: eine gehostete Seite, auf der der Kontoinhaber seinen Instagram-Benutzernamen und sein Passwort (sowie einen 2FA- oder Sicherheitsabfrage-Code, falls Instagram danach fragt) eingibt und die den Erfolg selbstständig meldet. Die Anmeldedaten gehen direkt an Instagram und werden nicht gespeichert. Geben Sie diesen Link an den Kontoinhaber weiter, anstatt das Passwort in Ihrer eigenen Benutzeroberfläche abzufragen. Der Link funktioniert für etwa 30 Minuten (connect_url_expires_at).

Instagram trennen (privat) #

DELETE /channels/instagram-private/{id}

Idempotent – wiederholte Aufrufe sind erfolgreich.

Follower synchronisieren #

POST /channels/instagram-private/{id}/sync-followers

Löst manuell eine Follower-Synchronisierung für ein verbundenes Konto aus – derselbe Vorgang, der automatisch im Hintergrund abläuft, hier jedoch als On-Demand-Aktion „Follower aktualisieren“ verfügbar. Es ruft die aktuelle Follower-Liste des Kontos ab, erfasst neue Follower und sendet (wenn bei einer Live-Kampagne die Follower-Ansprache aktiviert ist) neuen Followern eine erste Direktnachricht, bis zu einem täglichen Limit.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/yourbrand/sync-followers" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "accountId": "yourbrand",
  "totalFollowers": 1204,
  "newFollowers": 6,
  "dmsSent": 6,
  "isBaselineSeed": false
}

Diese fünf Felder sind die einzige Stelle auf dieser Seite, die camelCase anstelle von snake_case zurückgeben – so ist dieser Endpunkt aktuell konfiguriert, das ist kein Tippfehler. isBaselineSeed: true bedeutet, dass dies die allererste Synchronisierung nach dem Verbinden war, bei der nur die anfängliche Follower-Liste erfasst wird und niemals Direktnachrichten gesendet werden (daher ist dmsSent bei diesem Durchlauf immer 0).

Der allererste Aufruf für ein Konto kann eine Weile dauern (da die vollständige Follower-Liste durchlaufen wird); spätere Aufrufe sind schneller, da nur die neuen Follower abgeglichen werden. 404 bedeutet, dass das Konto nicht verbunden ist; 412 bedeutet, dass die Initialisierung der Verbindung noch nicht abgeschlossen ist – warten Sie kurz und versuchen Sie es erneut.

LINE #

LINE ist der einfachste Kanal für eine Verbindung, da keine Browser-Weiterleitung oder Abfrage erforderlich ist. Der Kunde erstellt einen Messaging-API-Kanal in der LINE Developers-Konsole, kopiert zwei Werte und Sie übermitteln diese in einem einzigen Aufruf. Anschließend geben Sie dem Kunden eine Webhook-URL, die er in die Konsole einfügen muss.

Schritt 1 – Verbindung mit den Kanal-Anmeldedaten herstellen #

POST /channels/line

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/line?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    "channel_secret": "CHANNEL_SECRET"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/line", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_access_token: "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    channel_secret: "CHANNEL_SECRET",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/line",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
        "channel_secret": "CHANNEL_SECRET",
    },
)
data = res.json()

Antwort

{
  "success": true,
  "status": "connected",
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Zwei Felder sind für Ihre nächsten Schritte wichtig:

• webhook_url – der Kunde muss dies in das Feld Webhook URL seines LINE-Kanals in der LINE Developers-Konsole einfügen (und „Use webhook“ aktivieren). Bis dies geschehen ist, gehen keine eingehenden Nachrichten ein. Zeigen Sie dies dem Kunden deutlich an.
• chat_mode_ok – wenn false, befindet sich das offizielle Konto im „Chat“-Modus und empfängt oder sendet keine Nachrichten, bis es im LINE Official Account Manager in den „Bot“-Modus geschaltet wird. Machen Sie Ihr Onboarding von diesem Flag abhängig und weisen Sie den Kunden an, den Modus zu wechseln.

Das channel_access_token und das channel_secret werden von keinem Endpunkt zurückgegeben. Speichern Sie diese bei sich, falls Sie sie erneut benötigen; andernfalls fügen Sie sie erneut aus der LINE-Konsole ein.

Die hier zurückgegebene bot_user_id ist die Verbindungskennung, die Sie in den unten aufgeführten Status-, Verifizierungs- und Trennungsaufrufen verwenden.

Schritt 2 – Erneute Überprüfung nach der Webhook-Einrichtung #

POST /channels/line/{botUserId}/verify-webhook

Nachdem der Kunde die Webhook-URL konfiguriert und in den Bot-Modus gewechselt hat, rufen Sie dies auf, um das gespeicherte Token erneut zu validieren und den zwischengespeicherten Chat-Modus zu aktualisieren.

curl -X POST "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "token_valid": true,
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Wenn token_valid den Wert false hat, authentifiziert das gespeicherte Zugriffstoken nicht mehr – lassen Sie den Kunden es in der Konsole neu ausstellen und rufen Sie POST /channels/line erneut mit dem neuen Token auf.

LINE-Status prüfen #

GET /channels/line/{botUserId}/status

curl "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../status" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "channel": "line",
  "status": "connected",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "is_active": true,
  "live": false
}

LINE verfügt über keinen Live-Status-Feed, daher ist live hier immer false – die Werte spiegeln den Status zum Zeitpunkt der Verbindung (oder der letzten Überprüfung) wider.

LINE trennen #

DELETE /channels/line/{botUserId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx..." \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "status": "removed", "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

Viber #

Viber wird auf die gleiche Weise wie LINE verbunden – fügen Sie das Auth-Token des Bots aus dem Viber Admin Panel in einem Aufruf ein – mit einem wichtigen Unterschied: Beim Verbinden wird unser Webhook sofort auf Ihrem Bot REGISTRIERT, daher ist danach kein separater Konsolenschritt erforderlich. Das bedeutet auch, dass ein Verbindungsversuch fehlschlagen kann, wenn unser Ingress die synchrone Webhook-Prüfung von Viber nicht beantworten kann, nicht nur, wenn das Token selbst falsch ist.

Schritt 1 – Verbinden mit dem Auth-Token des Bots #

POST /channels/viber

curl -X POST "https://api.youraiconnector.com/v1/channels/viber?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "444d5555e6666f7777a8888b9999c000" }'

Antwort

{
  "success": true,
  "status": "connected",
  "bot_id": "botIdFromViber",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "subscribers_count": 0,
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"]
}

Das Auth-Token wird von keinem Endpunkt zurückgegeben – speichern Sie es bei sich, falls Sie es erneut eingeben müssen. bot_id ist die Verbindungskennung, die für die Status-, Verifizierungs- und Trennungsaufrufe unten verwendet wird.

Viber-Status prüfen #

GET /channels/viber/{botId}/status

Meldet den gespeicherten Verbindungsstatus. Fügen Sie ?live=true hinzu, um den Bot zusätzlich bei Viber zu überprüfen und die zwischengespeicherte Webhook-Registrierung zu aktualisieren – nützlich, bevor Sie davon ausgehen, dass ein stummer Bot tatsächlich defekt ist.

curl "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/status?live=true" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "bot_id": "botIdFromViber",
  "channel": "viber",
  "status": "connected",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "registered_webhook": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "webhook_ok": true,
  "subscribers_count": 128,
  "is_active": true,
  "live": true
}

webhook_ok: false bedeutet, dass der Webhook des Bots nicht mehr auf uns verweist – eingehende Nachrichten kommen nicht an. Dies bedeutet normalerweise, dass ein anderes Tool den Bot danach verbunden hat (bei der Webhook-Registrierung von Viber gilt: der letzte Schreibzugriff gewinnt). Beheben Sie dies mit dem unten stehenden Re-Verify-Aufruf; der Kunde muss sein Token nicht erneut eingeben. live ist false, wenn die Antwort der letzte zwischengespeicherte Status ist und keine neue Überprüfung bei Viber stattgefunden hat.

Webhook erneut registrieren #

POST /channels/viber/{botId}/verify-webhook

Die Reparaturaktion für webhook_ok: false – registriert unseren Webhook erneut auf dem Bot unter Verwendung des bereits gespeicherten Auth-Tokens.

curl -X POST "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "token_valid": true, "webhook_ok": true, "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...", "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"] }

token_valid: false bedeutet, dass das gespeicherte Token nicht mehr funktioniert – verbinden Sie sich erneut mit POST /channels/viber und einem neuen Token.

Viber trennen #

DELETE /channels/viber/{botId}

Hebt die Registrierung unseres Webhooks auf der Seite von Viber auf (best-effort) und entfernt die Verbindung.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "status": "removed", "bot_id": "botIdFromViber", "webhook_removed": true }

TikTok #

Verfügbarkeit: Beta mit eingeschränkter Verfügbarkeit, pro Konto aktiviert. Das Verbinden von TikTok führt zu einem Berechtigungsfehler, bis das Konto dafür freigeschaltet wurde.

TikTok Business Messaging ist ein vollständiger OAuth-Kanal wie Meta, jedoch auf der Polling-Seite einfacher: Es gibt keinen dedizierten Status-Polling-Schritt, für den man etwas entwickeln müsste, da das verbundene Konto von selbst erscheint, sobald TikTok zurückleitet und die Verbindung geschrieben wurde. Der unten aufgeführte Status-Endpunkt dient zur Bestätigung des Zustands bei Bedarf (Support-Tools, Integritätsprüfungen) und nicht als etwas, das während der Verbindung in einer Schleife abgefragt werden muss.

Schritt 1 - TikTok-Verbindung starten #

POST /channels/tiktok/connect

Erfordert keine Anmeldedaten – der Kontoinhaber autorisiert den Vorgang vollständig in seinem Browser.

curl -X POST "https://api.youraiconnector.com/v1/channels/tiktok/connect?apiKey=YOUR_API_KEY"

Antwort

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://www.tiktok.com/v2/auth/authorize?client_key=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Öffnen Sie oauth_url im Browser des Kontoinhabers, damit dieser sich bei TikTok anmelden und den Zugriff genehmigen kann. Der Status läuft nach expires_at (etwa 30 Minuten) ab – falls er abläuft, beginnen Sie von vorn. Es gibt keine connect_url-Shortcut-Seite für TikTok; das selbstständige Öffnen von oauth_url ist der einzige Weg.

TikTok-Status prüfen #

GET /channels/tiktok/{openId}/status

openId ist die open_id des TikTok Business-Kontos, die bekannt ist, sobald der OAuth-Callback ausgeführt wurde.

curl "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok/status" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "open_id": "openIdFromTikTok",
  "channel": "tiktok",
  "status": "connected",
  "business_id": "openIdFromTikTok",
  "username": "mybusiness",
  "display_name": "My Business",
  "avatar_url": "https://...",
  "status_reason": null,
  "is_active": true,
  "live": false
}

TikTok bietet keine kostengünstige Live-Integritätsprüfung, daher ist live hier immer false – die Felder spiegeln das wider, was beim Verbinden (oder bei der letzten Token-Aktualisierung) geschrieben wurde. status: "reauth_required" mit gesetztem status_reason bedeutet, dass das Konto den Verbindungsprozess erneut durchlaufen muss; TikTok-Token werden automatisch jährlich rotiert, und dies wird angezeigt, falls diese Rotation jemals fehlschlägt.

TikTok trennen #

DELETE /channels/tiktok/{openId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "status": "removed", "open_id": "openIdFromTikTok" }

GoHighLevel #

GoHighLevel (GHL) ist eine CRM-Integration, kein Messaging-Kanal – das Verbinden verbraucht keinen Kanal-Slot im Plan, da es die bestehenden Kanäle des Kontos nutzt, anstatt einen neuen hinzuzufügen. Es ist zudem die einzige Integration auf dieser Seite, die mehr als eine Verbindung gleichzeitig halten kann: Jedes GHL-Unterkonto („Standort“), auf dem der Kunde die App installiert, erhält einen eigenen Eintrag.

Schritt 1 - GHL-Verbindung starten #

POST /channels/ghl/connect

curl -X POST "https://api.youraiconnector.com/v1/channels/ghl/connect?apiKey=YOUR_API_KEY"

Antwort

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://marketplace.gohighlevel.com/oauth/chooselocation?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "brand": "dmchamp",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Öffnen Sie oauth_url im Browser des Kontoinhabers, damit dieser einen GHL-Standort auswählen und den Zugriff genehmigen kann. Der Status läuft nach expires_at ab (ca. 30 Minuten).

GHL-Verbindungen auflisten #

GET /channels/ghl/status

Im Gegensatz zu anderen Kanälen ist dies nicht der Status einer einzelnen Verbindung – es werden alle Standorte aufgelistet, die das Konto verbunden hat.

curl "https://api.youraiconnector.com/v1/channels/ghl/status" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "connections": [
    {
      "location_id": "abc123location",
      "company_id": "xyz789company",
      "brand": "dmchamp",
      "status": "connected",
      "status_reason": null,
      "scopes": ["conversations.readonly", "conversations.write", "conversations/message.write"],
      "connected_at": "2026-06-01T10:00:00.000Z",
      "conversation_provider_id": "provider-id-in-ghl",
      "trigger_subscriptions": [
        { "id": "sub_1", "key": "InboundMessage", "workflow_id": "wf_123" }
      ]
    }
  ]
}

GHL-Standort trennen #

DELETE /channels/ghl/{locationId}

Löscht die Verbindung hier, wodurch alle Synchronisierungen und Trigger für diesen Standort gestoppt werden. Dies deinstalliert die App nicht auf der GHL-Seite – der Kunde entfernt sie aus seinen GHL-Marktplatz-Installationen, falls er dies ebenfalls wünscht.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/ghl/abc123location" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "status": "disconnected", "location_id": "abc123location" }

Telefonnummern (kaufen und freigeben) #

Anstatt eine bestehende Nummer zu verbinden, können Sie direkt eine neue WhatsApp-fähige Nummer kaufen. Suchen Sie nach verfügbaren Nummern, kaufen Sie eine und fragen Sie den Status ab, bis die Bereitstellung abgeschlossen ist.

Schritt 1 – Verfügbare Nummern suchen #

GET /phone-numbers/available?country_code=ISO2

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/phone-numbers/available",
    params={"country_code": "US"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Antwort

{
  "success": true,
  "phone_numbers": [
    {
      "phone_number": "+14155551234",
      "purchase_credits": 50,
      "monthly_credits": 50,
      "cost_usd": 1.15
    }
  ]
}

Jedes Ergebnis zeigt die einmalige purchase_credits und die wiederkehrende monthly_credits. Eine von der Plattform bereitgestellte Nummer kostet mindestens 50 Credits pro Monat, zuzüglich des monatlichen Preises des Anbieters, der beim Kauf und bei jeder Verlängerung berechnet wird. Verwenden Sie den purchase_credits / monthly_credits, den die Suche zurückgibt; leiten Sie niemals selbst einen Preis ab. Die erste Suche in einem neuen Konto stellt einige zugrunde liegende Ressourcen bereit, daher kann sie etwas langsamer sein als spätere Suchen.

Schritt 2 - Eine Nummer kaufen #

POST /phone-numbers

Verwenden Sie eine phone_number aus den Suchergebnissen.

cURL

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+14155551234",
    country_code: "US",
    display_name: "Support line",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/phone-numbers",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phone_number": "+14155551234",
        "country_code": "US",
        "display_name": "Support line",
    },
)
data = res.json()

Antwort

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "whatsapp_status": "PURCHASED",
  "outgoing_status": "PURCHASED",
  "status": "PURCHASED",
  "purchase_credits": 50,
  "monthly_credits": 50
}

Die Nummer beginnt im Status PURCHASED. Die WhatsApp-Registrierung erfolgt dann im Hintergrund: PURCHASED -> PENDING -> ONLINE.

Wenn der Kauf fehlschlägt, weil eine Geschäftsadresse fehlt oder ein anderes erforderliches Detail nicht festgelegt wurde, erhalten Sie einen 400 mit einer beschreibenden error. Richten Sie das fehlende Detail ein und versuchen Sie es erneut.

Schritt 3 - Abfragen bis ONLINE #

GET /phone-numbers/{phoneNumber}/status

Dies ist der gemeinsame Endpunkt für den Telefonnummernstatus – er funktioniert sowohl für gekaufte WhatsApp-Nummern als auch für Ihre anderen verbundenen Nummern.

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/phone-numbers/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/phone-numbers/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Antwort

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Schritt 4 - Eine Nummer freigeben #

DELETE /phone-numbers/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "phone_number": "+14155551234", "released": true }

Was dies bewirkt, hängt davon ab, wem die Nummer gehört.

Bei einer Nummer, die über die Plattform gemietet wurde, handelt es sich um eine echte Freigabe: Der WhatsApp-Absender wird abgemeldet, die Nummer wird an den Anbieter zurückgegeben und aus dem Konto entfernt. Es gilt eine 7-tägige Abklingzeit, während der die Nummer von niemandem zurückgekauft werden kann, und es werden keine Guthaben erstattet.

Bei einer Nummer, die das Konto selbst eingebracht hat (eigenes Twilio-Konto, eigene Meta-App oder WhatsApp Business-Konto oder ein Android-SMS-Gateway), entfernt der gleiche Aufruf sie lediglich aus dem Konto. Beim Upstream-Anbieter wird nichts freigegeben und es wird keine Abklingzeit (Cooldown) notiert, sodass die Nummer sofort wieder verbunden werden kann. Die WhatsApp-Senderregistrierung, falls vorhanden, bleibt möglicherweise erhalten oder auch nicht: Der Abbauvorgang versucht, den Sender mithilfe der vom Konto plattformverwalteten Twilio-Anmeldedaten zu löschen. Bei einem Konto, das sich noch in der verwalteten Einrichtung befindet, sind diese Anmeldedaten gültig und der Sender wird gelöscht, sodass eine erneute Verbindung eine erneute Registrierung erfordert. Bei einem Konto, das auf ein eigenes Twilio-Konto umgestellt wurde, kann die Löschung nicht authentifiziert werden und der Sender bleibt in diesem Konto registriert – eine erneute Verbindung bedeutet dann lediglich das erneute Anhängen des bestehenden Senders.

Eine bereits vorhandene Nummer hinzufügen (BYO) #

POST /phone-numbers/byo

Überspringt den oben genannten Such-und-Kauf-Prozess vollständig. Verwenden Sie dies, wenn das Konto eine eigene Nummer mitbringt (eigenes Twilio, eigenes Meta WhatsApp Business-Konto oder ein Android-SMS-Gateway), anstatt eine über die Plattform zu mieten. Dies zeichnet die Nummer nur auf – es werden keine Credits berechnet und hier wird nichts bei einem Anbieter bereitgestellt. Die Nummer bleibt inaktiv, bis der Kontoinhaber den WhatsApp-OAuth-Prozess abschließt, um einen Absender dafür zu registrieren (derselbe Prozess, den die Schaltfläche „Bring your own number“ im Dashboard startet).

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/byo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

Antwort (201 Created):

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "type": "BYO",
  "whatsapp_status": "ADDED",
  "outgoing_status": "ADDED",
  "is_active": false
}

Eine phone_number, die keine echte E.164-Nummer ist (oder die wie die WhatsApp-Testnummer von Meta aussieht, mit der niemals echte Kunden kontaktiert werden können), gibt 400 zurück. Das Hinzufügen einer Nummer, die bereits im Konto vorhanden ist – selbst wenn sie leicht anders geschrieben ist, wie z. B. die mexikanischen Formate +52 vs +521 – gibt 409 zurück, anstatt eine doppelte Zeile zu erstellen.

Eine Nummer als primär festlegen #

POST /phone-numbers/{phoneNumber}/set-primary

Setzt eine Nummer atomar auf is_active: true und jede andere Nummer im Konto auf is_active: false – das Konto hat während der Anfrage nie zwei aktive Nummern oder gar keine. is_active kann absichtlich nicht über den allgemeinen Update-Endpunkt festgelegt werden; dieser dedizierte Aufruf ist der einzige Weg, um die primäre Nummer zu ändern.

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/set-primary" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{
  "success": true,
  "phone_number": {
    "id": "+14155551234",
    "phone_number": "+14155551234",
    "display_name": "Support line",
    "channel": "whatsapp",
    "is_active": true,
    "whatsapp_status": "ONLINE"
  }
}

phone_number ist hier das vollständige Nummernobjekt (die gleiche Form, die GET /phone-numbers zurückgibt), nicht nur der String. Eine phoneNumber, die nicht zum Konto gehört, gibt 404 zurück.

Datensatz einer Nummer entfernen (ohne sie freizugeben) #

DELETE /phone-numbers/{phoneNumber}/record

Ein einfaches Löschen des Datensatzes der Nummer in diesem Konto – keine anbieterseitige Freigabe oder Abmeldung und keine 7-tägige Abklingzeit wie beim oben genannten Freigabeschritt. Verwenden Sie dies, um BYO-, WhatsApp Web-, Telegram- oder LINE-Datensätze oder einen veralteten Eintrag zu löschen, ohne den verwalteten Freigabeprozess zu durchlaufen. Im Gegensatz zu einer Freigabe ist das Löschen einer Nummer, die nicht zum Konto gehört, ein 404 und kein stiller Erfolg.

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/record" \
  -H "X-API-Key: YOUR_API_KEY"

Antwort

{ "success": true, "phone_number": "+14155551234", "deleted": true }

Einen Kanal einer Kampagne zuweisen #

Das Verbinden eines Kanals bringt Nachrichten in das Konto. Es entscheidet nicht, welcher KI-Agent sie beantwortet.

Das Routing wird über Einstiegspunkte (Entry Points) bei einem KI-Agenten gesteuert, nicht über Kampagnen. Jeder Kanal hat einen standardmäßigen Kanal-Einstiegspunkt, der den Agenten benennt, der neue, unbekannte Kontakte auf diesem Kanal beantwortet:

Bis ein Kanal einen Einstiegspunkt (Entry Point) hat, wird eine erste Nachricht von jemandem, mit dem Sie noch nie gesprochen haben, zwar gespeichert, aber nichts ruft sie ab und kein Assistent antwortet. Dies ist der Schritt, den die meisten Integrationen übersehen: Die Verbindung zu Instagram und die Erstellung eines Agenten reichen für sich genommen nicht aus – Sie müssen den Kanal auch auf den Agenten verweisen. Die vollständige Liste der Aufrufe – einschließlich eines Agenten pro WhatsApp-Nummer, Schlüsselwort- und Kommentarregeln – finden Sie in der Entry Points API.

POST /channels/campaign schreibt weiterhin die veraltete Routing-Karte für Kampagnen pro Kanal, die unten dokumentiert ist, aber diese Karte wird für das eingehende Routing in keinem Konto mehr herangezogen; sie wird nur noch für Rollbacks beibehalten. Bauen Sie nicht darauf auf.

Einen oder mehrere Kanäle routen (veraltete Kampagnen-Routing-Karte) #

POST /channels/campaign

Anfragefelder

Der Routing-Slot und die enabled_channels-Liste der Kampagne werden zusammen in einem atomaren Vorgang aktualisiert, sodass sie niemals voneinander abweichen können. Ein Kanal, der bereits einer anderen Kampagne zugewiesen ist, wird einfach auf diese neue Kampagne umgeleitet.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
    "channels": ["instagram", "messenger"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/campaign", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "NBCXrhqGPSFsd6MV7pRo",
    channels: ["instagram", "messenger"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
        "channels": ["instagram", "messenger"],
    },
)
data = res.json()

Antwort

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["instagram", "messenger"]
}

Voraussetzungen für das tatsächliche Auslösen des Routings #

Auf einem Konto, das noch die veraltete Kampagnen-Routing-Karte liest, ist das Routing als API-Aufruf erfolgreich, aber drei Dinge in der Kampagne entscheiden, ob eine echte eingehende Nachricht beantwortet wird. Prüfen Sie alle drei, wenn ein gerouteter Kanal stumm bleibt.

Der Keyword-Abgleich erfolgt jetzt über Einstiegspunkte — erstellen Sie einen Einstiegspunkt vom Typ keyword bei dem KI-Agenten, der antworten soll.

Eine Kampagne pro Kanal #

Jeder Kanal besitzt genau einen veralteten Routing-Slot. Das Routen einer zweiten Kampagne auf denselben Kanal weist den Slot stillschweigend neu zu und gibt 200 zurück — es gibt keinen Konfliktfehler. Die vorherige Kampagne bearbeitet weiterhin die Kontakte, die sie bereits hat; sie empfängt nur keine neuen mehr.

Routing eines Kanals löschen #

DELETE /channels/campaign/{channel}

Entfernt das Routing für einen einzelnen Kanal, unabhängig davon, auf welche Kampagne er derzeit verweist, und nimmt den Kanal aus der enabled_channels dieser Kampagne. Neue unbekannte Kontakte auf dem Kanal werden nicht mehr von einer Kampagne erfasst. Kontakte, die sich bereits in der Kampagne befinden, werden wie bisher weiterverarbeitet.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/campaign/instagram?apiKey=YOUR_API_KEY"

Antwort

{
  "success": true,
  "channel": "instagram",
  "cleared": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Es ist idempotent: Das Löschen eines Kanals, der nie geroutet wurde, gibt ebenfalls 200 zurück, mit cleared: false und campaign_id: null. Dieser Endpunkt erfordert die Funktion eingehende Kampagnen im Tarif; ohne diese erhalten Sie einen 403.

Verwenden Sie Ihre eigene Meta-App (Instagram + Messenger) #

Standardmäßig läuft die Instagram- + Messenger-Verbindung über die Meta-App der Plattform, sodass der Kontoinhaber den Namen dieser App auf dem Facebook-Zustimmungsbildschirm sieht. Wenn Sie möchten, dass auf dem Zustimmungsbildschirm stattdessen Ihre Marke angezeigt wird, können Sie Ihre eigene Meta-App registrieren und den gesamten Ablauf darüber leiten. Sobald dies konfiguriert ist, gilt es für Ihr Konto – an den oben genannten Verbindungsaufrufen ändert sich außer dem Branding nichts.

Dies gilt nur für Instagram + Messenger. WhatsApp, WhatsApp Web, Telegram- und LINE-Verbindungen sind von einer benutzerdefinierten Meta-App nicht betroffen.

Was Ihre App zuerst benötigt #

Dies ist der Teil, der Zeit in Anspruch nimmt und vollständig auf der Seite von Meta abläuft:

1. Eine App vom Typ Business, der die Produkte Messenger und Instagram hinzugefügt wurden.
2. Erweiterter Zugriff (über die Meta App Review) für: pages_show_list, pages_messaging, pages_manage_metadata, pages_read_engagement, instagram_basic, instagram_manage_messages. Ohne erweiterten Zugriff können nur Personen, die eine Rolle in Ihrer App innehaben, die Verbindung herstellen – die Verbindungen Ihrer Kunden werden fehlschlagen. Die App-Überprüfung dauert in der Regel einige Wochen und erfordert eine Unternehmensverifizierung.
3. Eine Facebook-Login-für-Business-Konfiguration, die innerhalb Ihrer App erstellt wurde und dieselben Berechtigungen gewährt. Ihre numerische Konfigurations-ID ist app-spezifisch, daher müssen Sie Ihre eigene erstellen.

Wenn Ihrer App eine der erforderlichen Berechtigungen fehlt, schlägt die Verbindung zum Zeitpunkt des Verbindungsaufbaus mit einem klaren Fehler fehl, der angibt, was fehlt (sichtbar im /status-Poll als byo_app_missing_permissions) – anstatt so auszusehen, als würde sie funktionieren, und dann bei der ersten Nachricht zu scheitern.

Schritt 1 - Speichern Sie Ihre App #

PUT /account-config/meta-app

Alle drei sind für den Facebook-Login-Ablauf erforderlich. Wenn Sie nur den weiter unten beschriebenen Instagram-Login-Token-Push-Pfad verwenden, können Sie diese vollständig weglassen.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "1234567890123456",
    "app_secret": "your-app-secret",
    "config_id": "9876543210987654"
  }'

Antwort

{
  "success": true,
  "app_id": "1234567890123456",
  "config_id": "9876543210987654",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram": "https://api.youraiconnector.com/v1/incoming-instagram-message/byo/YOUR_ACCOUNT_ID",
    "messenger": "https://api.youraiconnector.com/v1/incoming-messenger-message/byo/YOUR_ACCOUNT_ID"
  }
}

Schritt 2 - Konfigurieren Sie Ihre App für die Kommunikation mit uns #

Im Dashboard Ihrer Meta-App:

1. Webhooks - Legen Sie für die Produkte Instagram und Messenger die Callback-URL auf den passenden webhook_urls-Wert aus der Antwort und das Verify-Token auf verify_token fest. Abonnieren Sie die Felder messages, messaging_postbacks und comments.
2. Gültige OAuth-Redirect-URIs - Fügen Sie https://api.youraiconnector.com/v1/auth-meta-callback-handler hinzu, damit der Zustimmungsablauf zurückkehren kann.

GET /account-config/meta-app gibt jederzeit dasselbe Einrichtungsmaterial zurück; DELETE /account-config/meta-app entfernt die App (zukünftige Verbindungen greifen wieder auf die Plattform-App zurück – entfernen Sie auch das Webhook-Abonnement innerhalb Ihrer App).

Schritt 3 - Wie gewohnt verbinden #

Es ändert sich sonst nichts. POST /channels/meta/connect (und die gehostete connect_url-Seite) verwendet automatisch Ihre App für Ihr Konto; der uses_byo_meta_app: true der Antwort bestätigt, welche App auf dem Zustimmungsbildschirm angezeigt wird. Das Senden von Nachrichten, die Seitenauswahl und das Trennen der Verbindung funktionieren identisch.

Eigene Instagram-Login-App verwenden (Token-Push) #

Der obige Abschnitt behandelt den Facebook-Login-Ablauf, bei dem das Konto über eine Facebook-Seite verbunden wird. Meta bietet auch die Instagram-API mit Instagram-Login (Business-Login für Instagram) an: Der Kontoinhaber authentifiziert sich direkt bei Instagram, ohne dass ein Facebook-Konto oder eine Facebook-Seite erforderlich ist.

Wenn Ihre Plattform bereits eine eigene Meta-App mit diesem Produkt betreibt, benötigen Sie unsererseits überhaupt keinen OAuth-Ablauf. Ihre Kunden autorisieren Ihre App, und Sie übermitteln uns die fertigen Anmeldedaten pro Konto:

1. Sie speichern die Anmeldedaten Ihrer Instagram-App einmalig (damit wir Ihre Webhooks verifizieren können).
2. Pro Konto übermitteln Sie die Instagram-Professional-Konto-ID + das langlebige Instagram-Benutzer-Token, das Ihre App erhalten hat.
3. Sie verweisen den Instagram-Messaging-Webhook Ihrer App auf uns. Ereignisse für Konten, die Sie nie übermittelt haben, werden bestätigt und ignoriert.
4. Sie verwalten den Token-Lebenszyklus: Aktualisieren Sie Token in Ihrem eigenen System und übermitteln Sie jedes aktualisierte Token mit demselben Aufruf. Wir aktualisieren ein übermitteltes Token niemals selbst.

Was Ihre App zuerst benötigt #

• Das Instagram-Produkt („API-Einrichtung mit Instagram-Login“), das Ihrer Meta-App hinzugefügt wurde. Dieses Produkt hat ein eigenes Paar aus App-ID und App-Secret, getrennt von der Facebook-App-ID/dem App-Secret – Sie finden diese im Einrichtungsbereich des Produkts.
• Erweiterter Zugriff (über Meta App Review) für instagram_business_basic und instagram_business_manage_messages (fügen Sie instagram_business_manage_comments hinzu, wenn Sie Kommentar-Automatisierungen verwenden). Ohne diesen können nur Personen mit einer Rolle in Ihrer App diese autorisieren.

Schritt 1 - Speichern Sie Ihre Instagram-App-Anmeldedaten #

Derselbe Endpunkt wie oben – senden Sie das Instagram-Paar an PUT /account-config/meta-app. Die Facebook-Felder werden für diesen Pfad nicht benötigt: Senden Sie das Paar allein, wenn Sie nur den Instagram-Login verwenden, oder zusammen mit den Facebook-Feldern, wenn Sie beides verwenden. Ein Speichervorgang beschreibt immer die gesamte Einstellung; das Set, das Sie weglassen, wird daher entfernt.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instagram_app_id": "1122334455667788",
    "instagram_app_secret": "your-instagram-app-secret"
  }'

Antwort – enthält die Instagram-Login-Webhook-URL (die instagram- und messenger-URLs erscheinen nur, wenn auch die Facebook-Felder gespeichert sind):

{
  "success": true,
  "instagram_app_id": "1122334455667788",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram_login": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
  }
}

Setzen Sie im Webhooks-Bereich Ihrer App für das Instagram-Produkt die Callback-URL auf webhook_urls.instagram_login, das Verify-Token auf verify_token und abonnieren Sie die Felder messages und comments.

Schritt 2 - Token pro Konto übermitteln #

PUT /channels/instagram-login/token

Funktioniert mit sub_account_id wie jede andere Route, sodass ein Agenturschlüssel seine gesamte Flotte bereitstellen kann.

curl -X PUT "https://api.youraiconnector.com/v1/channels/instagram-login/token?apiKey=YOUR_AGENCY_KEY&sub_account_id=CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ig_user_id": "17841400000000000",
    "access_token": "IGAAR…",
    "expires_at": "2026-11-01T00:00:00Z"
  }'

Antwort

{
  "success": true,
  "ig_user_id": "17841400000000000",
  "username": "acme.studio",
  "expires_at": "2026-11-01T00:00:00.000Z",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
}

Als Teil der Übermittlung abonnieren wir Ihre App für die Webhooks dieses Kontos (subscribed_apps mit dem übermittelten Token), sodass Nachrichten ohne zusätzlichen Aufruf Ihrerseits fließen.

Aktualisierung - Senden Sie das aktualisierte Token an denselben Endpunkt mit demselben ig_user_id; dies aktualisiert das gespeicherte Token und das Ablaufdatum direkt.

Konflikte - Ein Instagram-Konto ist niemals auf zwei Verbindungen gleichzeitig aktiv. Wenn das Konto bereits an anderer Stelle verbunden ist oder über den Facebook-Seiten-Flow mit diesem Konto verknüpft wurde, gibt der Push einen 409 zurück, der Ihnen mitteilt, welche Verbindung zuerst getrennt werden muss. Eine Verbindung über den Facebook-Flow wird niemals automatisch ersetzt, da sie möglicherweise auch für Messenger verwendet wird.

Schritt 3 - Trennen, wenn ein Client geht #

DELETE /channels/instagram-login/token (gleiche Authentifizierung und sub_account_id) hebt die Webhooks nach bestem Bemühen auf und entfernt die gespeicherten Anmeldeinformationen. Dies ist immer erfolgreich, selbst wenn das Token bereits abgelaufen ist – und sobald die Anmeldeinformationen entfernt wurden, werden die Webhook-Ereignisse dieses Kontos ignoriert.

Tipps für den Aufbau eines zuverlässigen Wrappers #

• Sanft abfragen. Alle paar Sekunden reicht völlig aus. Stoppen Sie, sobald Sie einen Endzustand (connected / ONLINE oder einen Fehlerstatus) erreichen, und legen Sie ein sinnvolles Gesamt-Timeout für die Schleife fest (die Browser-/QR-Schritte laufen ab, siehe jedes expires_at).
• Telefonnummern im Pfad URL-kodieren. Das führende + sollte als %2B gesendet werden. Die Endpunkte stellen auch reine Ziffern wieder her, aber die Kodierung ist die sichere Standardeinstellung.
• Erwarten Sie niemals Geheimnisse zurück. Zugriffstoken, Kanalschlüssel und Seitentoken werden akzeptiert oder gespeichert, aber niemals in einer Antwort zurückgegeben.
• Behandeln Sie das Auth-Gate. Ein 403 bedeutet, dass der API-Zugriff nicht im Plan enthalten ist oder dass der Kanal, den Sie verbinden, nicht im Plan des Kontos enthalten ist. Siehe API-Zugriff.
• Beachten Sie das Ratenlimit. Authentifizierte Anfragen sind auf 300 pro Minute begrenzt; ein 429 bedeutet, dass Sie pausieren und es erneut versuchen sollten. Siehe Authentifizierung.

Nächste Schritte #

• Authentifizierung - die vier akzeptierten Authentifizierungsformen und das Fehlerformat.
• API-Zugriff - Generierung und Verwaltung Ihres API-Schlüssels.