# 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.
::: note
**Hinweis:** Stellen Sie vor Beginn sicher, dass der API-Zugriff für Ihren Plan aktiviert ist und Sie über einen API-Schlüssel verfügen. Informationen zur Generierung finden Sie unter [API-Zugriff](../integrations/api-access.md). Alle unten aufgeführten Anfragen verwenden die Basis-URL `https://api.youraiconnector.com/v1` und Sie müssen jede Anfrage authentifizieren. Unter [Authentifizierung](authentication.md) finden Sie die vier akzeptierten Formen – die Beispiele hier verwenden den `X-API-Key`-Header, wobei pro Seite ein cURL-Beispiel die einfachere `?apiKey=`-Abfrageform zeigt.
:::
---
## 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**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY"
```
**JavaScript**
```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**
```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**
```json
{
"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:
| `status` | Bedeutung |
|---|---|
| `pending` | Zustimmung noch nicht abgeschlossen. Bitte warten. |
| `token_received` | Autorisiert, aber die Liste der Seiten wird noch geladen. |
| `pages_loaded` | Seiten sind verfügbar – weiter zu Schritt 3. |
| `connected` | Eine Seite wurde ausgewählt und der Kanal ist aktiv. |
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/channels/meta/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```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**
```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)**
```json
{
"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
```
```bash
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**
```bash
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**
```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**
```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**
```json
{
"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.
| Abfrageparameter | Erforderlich | Beschreibung |
|---|---|---|
| `platform` | Ja | `instagram` oder `facebook`. Alles andere gibt einen `400` zurück. |
| `limit` | Nein | Anzahl der zurückzugebenden Beiträge, `1`-`50`. Standardwert ist `25`. |
| `after` | Nein | Cursor für die nächste Seite – übergeben Sie den `nextCursor`-Wert aus der vorherigen Antwort. |
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/channels/meta/posts?platform=instagram&limit=25" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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:
| `reason` | Was zu tun ist |
|---|---|
| _(abwesend)_ | Es ist noch keine Seite verbunden – führen Sie zuerst den Verbindungsprozess aus. |
| `no_instagram_account` | Eine Facebook-Seite ist verbunden, aber kein Instagram-Business-Konto ist damit verknüpft. Facebook-Beiträge werden weiterhin korrekt aufgelistet. |
| `token_expired` | Die gespeicherten Seitenzugangsdaten funktionieren nicht mehr – verbinden Sie den Kanal erneut. |
### Trennen der Instagram + Messenger-Verbindung
```
DELETE /channels/meta
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/meta" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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**
```bash
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**
```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**
```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.
```
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `phone_number` | Ja | Die zu verbindende Nummer im E.164-Format (z. B. `+14155551234`). |
| `only_waba_sharing` | Nein | Beschränkt die Autorisierung auf die Freigabe eines bestehenden WhatsApp Business-Kontos und überspringt die Einrichtung eines neuen Absenders. Standardwert ist `false`. |
| `retry` | Nein | Führt die Autorisierung für eine Nummer erneut aus, deren vorheriger Versuch nicht abgeschlossen wurde. Standardwert ist `false`. |
| `business_name` | Nein | Kosmetische Überschreibung für den auf dem Zustimmungsbildschirm angezeigten Unternehmensnamen (max. 256 Zeichen). Wird nicht gespeichert. |
| `description` | Nein | Kosmetische Überschreibung für die auf dem Zustimmungsbildschirm angezeigte Unternehmensbeschreibung (max. 256 Zeichen). Wird nicht gespeichert. |
**Antwort**
```json
{
"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**
```bash
curl "https://api.youraiconnector.com/v1/channels/whatsapp/connect/+14155551234/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```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**
```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**
```json
{
"success": true,
"phone_number": "+14155551234",
"channel": "whatsapp",
"status": "ONLINE",
"status_reason": null,
"live": true
}
```
Das Feld `status` kann folgende Werte annehmen:
| `status` | Bedeutung |
|---|---|
| `PENDING` | Autorisiert, Genehmigung läuft noch. Bitte weiter abfragen. |
| `ONLINE` | Verbunden und bereit zum Senden. |
| `RATE_LIMITED` | Zu viele Versuche – warten Sie vor einem erneuten Versuch. |
| `REGISTRATION_FAILED` | Einrichtung konnte nicht abgeschlossen werden. |
| `DELETED` | Die Registrierung existiert nicht mehr. |
`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}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp/+14155551234" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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**
```bash
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**
```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**
```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()
```
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `phone_number` | Ja | Die zu verbindende WhatsApp-Nummer im E.164-Format. |
| `proxy_country` | Nein | ISO 3166-1 alpha-2 Ländercode für die Routing-Region. Wird bei Weglassen automatisch aus der Nummer erkannt. |
| `force_new` | Nein | Bestehende Sitzung verwerfen und neue Kopplung starten. Standardwert ist `false`. |
| `import_contacts` | Nein | Vorhandene Kontakte des Geräts bei der ersten Verbindung importieren. Standardwert ist `false`. |
| `pause_ai_for_imported_contacts` | Nein | Beim Importieren von Kontakten automatisierte Antworten für diese pausiert lassen. Standardwert ist `true`. |
| `import_existing_chats` | Nein | Vorhandenen Chatverlauf importieren (erfordert `import_contacts: true`). Standardwert ist `false`. |
**Antwort**
```json
{
"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**
```bash
curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```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 ![]()
for the user to scan.
```
**Python**
```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**
```json
{
"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 `![]()
` 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**
```bash
curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```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**
```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**
```json
{
"success": true,
"phone_number": "+15551230000",
"status": "connected",
"has_qr": false,
"qr_expires_at": null,
"last_activity": null,
"message_count": null,
"proxy": null,
"live": true
}
```
| `status` | Bedeutung |
|---|---|
| `not_initialized` | Noch keine Sitzung (endgültiger Fehler). |
| `qr_pending` | Warten auf das Scannen des QR-Codes. |
| `connecting` | Gescannt, Einrichtung wird abgeschlossen. |
| `connected` / `open` | Verknüpft und aktiv – dies ist der Erfolg. |
| `disconnected` | Sitzung beendet (endgültiger Fehler). |
### Trennen einer WhatsApp Web-Sitzung
```
DELETE /channels/whatsapp-web/connections/{phoneNumber}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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**
```bash
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**
```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**
```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()
```
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `phone_number` | Ja | Die Telefonnummer des zu verbindenden Kontos im E.164-Format. |
| `mode` | Nein | `code` (Standard) sendet einen einmaligen Anmeldecode an das Konto; `qr` gibt ein Anmelde-Token und eine QR-URL zur Anzeige zurück. |
| `proxy_country` | Nein | ISO 3166-1 alpha-2 Ländercode für die ausgehende Netzwerkroute. |
| `force_new` | Nein | Wenn `true`, wird jede bestehende Sitzung verworfen und eine neue gestartet. |
**Antwort**
```json
{
"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**
```bash
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**
```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**
```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**
```json
{
"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**
```bash
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**
```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**
```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**
```json
{
"success": true,
"phone_number": "+14155550100",
"status": "connected",
"telegram_user_id": "100000001",
"username": "myhandle"
}
```
### Telegram-Status prüfen
```
GET /channels/telegram/connect/{phoneNumber}/status
```
```bash
curl "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/telegram/+14155550100" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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**
```json
{
"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.
```bash
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**
```json
{
"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.
```bash
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.
```bash
curl "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/yourbrand/sync-followers" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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**
```bash
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**
```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**
```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()
```
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `channel_access_token` | Ja | Das langlebige Messaging-API-Kanal-Zugriffstoken des offiziellen Kontos. Wird zum Senden und Empfangen von Nachrichten verwendet. |
| `channel_secret` | Ja | Das Messaging-API-Kanal-Geheimnis, das zur Überprüfung eingehender Ereignissignaturen verwendet wird. |
| `channel_id` | Nein | Die numerische Kanal-ID. Nur zu Informationszwecken. |
**Antwort**
```json
{
"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.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../verify-webhook" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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
```
```bash
curl "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx..." \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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
```
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `auth_token` | Ja | Das Auth-Token des Bots aus dem Viber Admin Panel (My Bot Settings). |
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/viber?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "auth_token": "444d5555e6666f7777a8888b9999c000" }'
```
**Antwort**
```json
{
"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.
```bash
curl "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/status?live=true" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/verify-webhook" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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.
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/tiktok/connect?apiKey=YOUR_API_KEY"
```
**Antwort**
```json
{
"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.
```bash
curl "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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
```
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `brand` | Nein | Über welchen GHL-Marktplatzeintrag die Autorisierung erfolgen soll. Standardmäßig wird der Standardeintrag verwendet – dies ist nur relevant, wenn für Ihre Bereitstellung mehr als eine Marktplatz-App konfiguriert ist. |
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/ghl/connect?apiKey=YOUR_API_KEY"
```
**Antwort**
```json
{
"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.
```bash
curl "https://api.youraiconnector.com/v1/channels/ghl/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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.
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/ghl/abc123location" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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.
::: note
**Hinweis:** Hier gekaufte Nummern sind WhatsApp-fähig. Die Registrierung des WhatsApp-Absenders erfolgt nach dem Kauf im Hintergrund. Sie müssen daher den Status abfragen, bis dieser `ONLINE` erreicht, bevor Sie Nachrichten senden. Guthaben wird beim Kauf abgezogen und bei der Freigabe der Nummer **nicht** erstattet.
:::
### Schritt 1 – Verfügbare Nummern suchen
```
GET /phone-numbers/available?country_code=ISO2
```
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US&apiKey=YOUR_API_KEY"
```
**JavaScript**
```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**
```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()
```
| Abfrageparameter | Erforderlich | Beschreibung |
|---|---|---|
| `country_code` | Ja | ISO 3166-1 alpha-2 Ländercode für die Suche (z. B. `US`, `GB`, `NL`). |
| `type` | Nein | Bevorzugte Nummernkategorie, `local` oder `mobile`. Es können dennoch beide Kategorien zurückgegeben werden. |
**Antwort**
```json
{
"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**
```bash
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**
```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**
```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()
```
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `phone_number` | Ja | Eine Nummer aus der Suche nach verfügbaren Nummern im E.164-Format. |
| `country_code` | Ja | ISO 3166-1 alpha-2 Ländercode (z. B. `US`). |
| `display_name` | Nein | Eine benutzerfreundliche Bezeichnung. Standardmäßig die Telefonnummer. |
| `category` | Nein | Optionale Kategoriebezeichnung. |
**Antwort**
```json
{
"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**
```bash
curl "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```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**
```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**
```json
{
"success": true,
"phone_number": "+14155551234",
"channel": "whatsapp",
"status": "ONLINE",
"status_reason": null,
"live": true
}
```
### Schritt 4 - Eine Nummer freigeben
```
DELETE /phone-numbers/{phoneNumber}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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).
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `phone_number` | Ja | Die hinzuzufügende Nummer im E.164-Format (z. B. `+14155551234`). |
| `country_code` | Ja | ISO 3166-1 alpha-2 Ländercode (z. B. `US`). |
| `display_name` | Nein | Ein benutzerfreundliches Label. Standardmäßig die Telefonnummer. |
| `category` | Nein | Optionales Kategorie-Label. |
```bash
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`):
```json
{
"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.
```bash
curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/set-primary" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{
"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.
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/record" \
-H "X-API-Key: YOUR_API_KEY"
```
**Antwort**
```json
{ "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:
| Was Sie tun möchten | Aufruf |
|---|---|
| Einen Kanal auf den Agenten verweisen, der ihn beantworten soll | `PUT /entry-points/channel-defaults` mit Body `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| Prüfen, ob die Einstiegspunkt-Hierarchie für das Konto aktiv ist | `GET /entry-points/routing-status`, was `{ "success": true, "cutover_enabled": true }` zurückgibt, sobald Einstiegspunkte das Routing des Kontos bestimmen |
| Einen Kanal ohne antwortenden Agenten belassen | `DELETE /entry-points/channel-defaults?channel=instagram` |
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](entry-points.md).
`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**
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `campaign_id` | Ja | Die Kampagne, die neue Kontakte auf diesen Kanälen beantworten soll. Muss zum Konto gehören. |
| `channels` | Ja | Ein nicht leeres Array von Kanälen, die zugewiesen werden sollen. Erlaubt: `whatsapp`, `whatsapp_web`, `telegram`, `instagram`, `messenger`, `chat_widget`, `custom_channel`, `sms`, `email`. |
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**
```bash
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**
```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**
```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**
```json
{
"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.
| Anforderung | Was sonst passiert |
|---|---|
| `type` ist `Incoming from Unknown Contacts` oder `Combined` | Die Anfrage wird mit `400` abgelehnt. Ausgehende und Keyword-Kampagnen können keinen Routing-Slot belegen. |
| `status` ist `Live` | Das Routing wird gespeichert, greift aber nichts auf. Eine `Draft`-Kampagne ist die häufigste Ursache für "Ich habe es geroutet und nichts passiert". |
| `ai_mode` ist `true` | Der Kontakt wird erstellt und die Nachricht gespeichert, aber der Assistent antwortet nie. |
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.
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/campaign/instagram?apiKey=YOUR_API_KEY"
```
**Antwort**
```json
{
"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`
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `app_id` | Ja | Ihre Meta-App-ID (Einstellungen → Basis). |
| `app_secret` | Ja | Ihr Meta-App-Geheimnis. Wird vor der Speicherung bei Meta verifiziert und dann verschlüsselt. Wird von keinem Endpunkt zurückgegeben. |
| `config_id` | Ja | Die numerische ID der Facebook-Login-für-Business-Konfiguration innerhalb Ihrer 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.
```bash
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**
```json
{
"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.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `instagram_app_id` | Zusammen | Die numerische App-ID des Instagram-Produkts selbst (nicht die Facebook-App-ID). |
| `instagram_app_secret` | Zusammen | Das App-Secret des Instagram-Produkts selbst. Wird im Ruhezustand verschlüsselt und niemals zurückgegeben. |
```bash
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):
```json
{
"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.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `ig_user_id` | Ja | Die **Instagram-Professional-Konto-ID** – das Feld `user_id` aus `GET https://graph.instagram.com/v21.0/me?fields=user_id,username`. Dies ist dieselbe ID, die Instagram-Webhooks als `entry.id` übertragen. ⚠️ Dies ist **nicht** das Feld `id` aus `/me` – dieses ist App-spezifisch und unterscheidet sich je nach Meta-App. Das Übermitteln der App-spezifischen ID führt zu einem `400`, das auf den Fehler hinweist. |
| `access_token` | Ja | Das langlebige Instagram-Benutzer-Token, das Ihre App für dieses Konto erhalten hat. Wird vor der Speicherung live gegen Instagram validiert: Das Token muss funktionieren und zu `ig_user_id` gehören. |
| `expires_at` | Nein | ISO-8601-Ablaufdatum des Tokens. Senden Sie alternativ `expires_in` (Sekunden). Standardmäßig 60 Tage. |
| `username` | Nein | Der @Handle des Kontos; wir lesen ihn ohnehin von Instagram aus. |
```bash
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**
```json
{
"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](../integrations/api-access.md).
- **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](authentication.md).
## Nächste Schritte
- [Authentifizierung](authentication.md) - die vier akzeptierten Authentifizierungsformen und das Fehlerformat.
- [API-Zugriff](../integrations/api-access.md) - Generierung und Verwaltung Ihres API-Schlüssels.