Eine Integration von Grund auf erstellen
Dieser Leitfaden führt Sie durch alles, was Sie benötigen, um Your AI Connector aus Ihrem eigenen Code heraus auszuführen, ohne jemals das Dashboard öffnen zu müssen. Am Ende haben Sie eine minimale Integration erstellt, die:
- Authentifizierung mit einem API-Schlüssel
- Erstellen eines KI-Agenten und Konfigurieren seines Assistentenverhaltens
- Verbinden eines Messaging-Kanals (wir verwenden WhatsApp Web als Beispiel) und Zuweisen an den Agenten
- Importieren von Kontakten
- Senden und Lesen von Nachrichten
- Lesen von Analysedaten
- Abonnieren von Webhooks für Echtzeit-Ereignisse
Jeder Schritt verlinkt auf den vollständigen Ressourcenleitfaden, damit Sie bei Bedarf tiefer in die Details eintauchen können. Diese Seite ist die Karte; die Ressourcenleitfäden sind das Gelände.
Bevor Sie beginnen. Der API-Zugriff ist eine kostenpflichtige Funktion. Wenn Ihr Plan diesen nicht beinhaltet, gibt jede Anfrage
403zurück. Siehe API-Zugriff, um zu bestätigen, dass er aktiviert ist, und Authentifizierung für alle Möglichkeiten, Ihren Schlüssel zu übermitteln.
Alle Pfade unten sind relativ zur Basis-URL:
https://api.youraiconnector.com/v1
Schritt 1 — API-Schlüssel abrufen und erste Anfrage stellen
Ihr API-Schlüssel befindet sich in der App unter Einstellungen → Integrationen → API-Schlüssel — ein eigener Bereich unter Integrationen, getrennt von Webhooks, der nur erscheint, wenn der API-Zugriff im Plan enthalten ist. Generieren Sie einen, kopieren Sie ihn und speichern Sie ihn an einem sicheren Ort (einem serverseitigen Secret-Store oder einer Umgebungsvariablen — niemals im Browser-Code). Vollständige Anweisungen finden Sie unter API-Zugriff.
Sobald Sie einen Schlüssel haben, bestätigen Sie dessen Funktion, indem Sie den Health-Endpunkt aufrufen. Es gibt verschiedene Möglichkeiten, den Schlüssel zu senden; die einfachste ist der ?apiKey=-Abfrageparameter, aber für echten Code bevorzugen Sie den X-API-Key-Header, damit der Schlüssel niemals in Server-Logs oder im Browser-Verlauf landet.
cURL
curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"
JavaScript
const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };
const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }
Python
import requests
BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}
res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json()) # { "success": true, ... }
Jede erfolgreiche Antwort ist in denselben Umschlag verpackt – ein success: true-Feld plus die Ergebnisdaten. Fehler geben success: false mit einer error-Nachricht und einem error_code zurück. Siehe Fehler & Paginierung für die vollständige Liste und wie Listen-Endpunkte mit ?limit und ?cursor paginiert werden.
Ratenbegrenzung. Authentifizierte Anfragen sind auf 300 pro Minute begrenzt (mit einer höheren Obergrenze von 1.200 pro Minute und Konto). Bei Überschreitung wird
429zurückgegeben; warten Sie kurz und versuchen Sie es erneut.
Schritt 2 — Erstellen eines KI-Agenten
Ein KI-Agent ist die Einheit, die das Verhalten Ihres Assistenten definiert: seine Anweisungen, sein Ziel, seine aktiven Zeiten und wie er mit Kontakten kommuniziert. Da er die Konversationen beantwortet, ist dies der logische erste Schritt.
Erstellen Sie einen mit POST /agents. name ist das einzige Feld, das vorab gesendet werden muss; alles andere kann mit dem unten stehenden bot-config-Aufruf festgelegt werden.
cURL
curl -X POST "https://api.youraiconnector.com/v1/agents" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Inbound WhatsApp Leads",
"language": "en"
}'
JavaScript
const res = await fetch(`${BASE}/agents`, {
method: "POST",
headers,
body: JSON.stringify({
name: "Inbound WhatsApp Leads",
language: "en",
}),
});
const { agent_id } = await res.json();
Python
res = requests.post(
f"{BASE}/agents",
headers=HEADERS,
json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]
Eine erfolgreiche Erstellung gibt 201 mit der neuen ID zurück:
{
"success": true,
"agent_id": "abc123agent"
}
Speichern Sie die agent_id — Sie werden sich darauf beziehen, wenn Sie Kanäle zuweisen.
Konfigurieren des Assistenten
PUT /agents/{agentId}/bot-config legt das Verhalten des Assistenten fest. Es führt die von Ihnen gesendeten Felder mit der bestehenden Konfiguration zusammen, sodass alles, was Sie weglassen, erhalten bleibt:
curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
"goal": "Book a discovery call.",
"ai_speed": "balanced"
}'
Legen Sie aktive Zeiten mit PUT /agents/{agentId}/active-hours fest, damit der Assistent nur während der Geschäftszeiten antwortet; außerhalb dieser Zeitfenster antwortet er nicht automatisch.
Wissensdatenbank. Damit der Assistent auf Basis Ihrer eigenen Inhalte antwortet, fügen Sie FAQs hinzu. Siehe den FAQ-Leitfaden.
Legacy: klassische Kampagnen. Konten, die noch über eine Kampagnen-Seite verfügen, erstellen dasselbe Assistentenverhalten stattdessen für eine Kampagne (
POST /campaignsmit einemtype- und einembot-Objekt, dannPUT /campaigns/{campaignId}/bot-config). Die vollständige Liste der Kampagnenfelder und Lebenszyklus-Steuerungen finden Sie im Kampagnen-Leitfaden. Wenn Sie etwas Neues aufbauen, erstellen Sie einen Agenten.
Schritt 3 – Einen Kanal verbinden
Ein Agent benötigt eine Möglichkeit, Nachrichten zu senden und zu empfangen. Sieben Verbindungsabläufe können über die API gesteuert werden: WhatsApp Business, WhatsApp Web, Instagram und Messenger zusammen (ein gemeinsamer Meta-Ablauf), persönliche Instagram-Konten, Telegram, LINE und Viber. Die übrigen Kanäle — darunter SMS, E-Mail, das Chat-Widget und benutzerdefinierte Kanäle — werden im Dashboard statt über REST eingerichtet. Sobald sie verbunden sind, funktionieren die Messaging-, Kontakt- und Routing-Endpunkte für sie auf genau dieselbe Weise. GET /channels ist die aktuelle Quelle der Wahrheit dafür, was für ein bestimmtes Konto tatsächlich verbunden ist:
curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"
Die vollständigen Abläufe zum Verbinden/Trennen für jeden Kanal sind im Kanal-Leitfaden dokumentiert. Im Folgenden gehen wir WhatsApp Web von Anfang bis Ende durch, da es das interessanteste Muster zeigt: einen QR-Code-Kopplungsprozess, den Ihr Wrapper rendern und abfragen muss.
Praxisbeispiel: WhatsApp Web per QR-Code koppeln
Die Kopplung mit WhatsApp Web ist ein Prozess aus drei Aufrufen – starten, QR-Code abrufen, abfragen bis zur Verbindung.
1. Die Kopplungssitzung starten. Übergeben Sie die Nummer, die Sie verbinden möchten, im E.164-Format.
curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone_number": "+15551230000" }'
await fetch(`${BASE}/channels/whatsapp-web/connections`, {
method: "POST",
headers,
body: JSON.stringify({ phone_number: "+15551230000" }),
});
requests.post(
f"{BASE}/channels/whatsapp-web/connections",
headers=HEADERS,
json={"phone_number": "+15551230000"},
)
2. Den QR-Code abrufen und dem Benutzer anzeigen. Fragen Sie diesen alle 10–15 Sekunden ab. Die Antwort enthält den rohen qr_code-Payload (rendern Sie ihn selbst als QR-Bild) und einen qr_data_url, der direkt angezeigt werden kann.
curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"
{
"success": true,
"phone_number": "+15551230000",
"status": "qr_pending",
"qr_code": "2@abc...",
"qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}
Fügen Sie in der Benutzeroberfläche Ihres Wrappers den qr_data_url direkt in ein <img src="..."> ein und bitten Sie den Benutzer, ihn über WhatsApp → Verknüpfte Geräte auf seinem Telefon zu scannen. Wenn der QR-Code abläuft (eine 410-Antwort), starten Sie erneut bei Schritt 1, um einen neuen zu erhalten.
3. Den Status abfragen, bis die Verbindung hergestellt ist. Nachdem der Benutzer den Scan durchgeführt hat, fragen Sie den Status-Endpunkt weiter ab, bis er connected meldet (der Dienst kann auch open melden). Behandeln Sie disconnected und not_initialized als endgültige Fehler.
import time
PHONE = "+15551230000"
while True:
res = requests.get(
f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
headers=HEADERS,
)
status = res.json()["status"]
if status in ("connected", "open"):
print("Connected!")
break
if status in ("disconnected", "not_initialized"):
raise RuntimeError(f"Pairing failed: {status}")
time.sleep(5)
async function waitForConnection(phone) {
while (true) {
const res = await fetch(
`${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
{ headers }
);
const { status } = await res.json();
if (status === "connected" || status === "open") return;
if (status === "disconnected" || status === "not_initialized") {
throw new Error(`Pairing failed: ${status}`);
}
await new Promise((r) => setTimeout(r, 5000));
}
}
Hinweis. Für jede verbundene WhatsApp Web-Nummer fällt eine wiederkehrende monatliche Wartungsgebühr an, bis Sie sie trennen (
DELETE /channels/whatsapp-web/connections/{phoneNumber}).
Zuweisen des Kanals an Ihren Agenten
Durch das Verbinden eines Kanals wird dieser funktionsfähig; durch das Zuweisen legen Sie fest, welcher KI-Agent neue eingehende Konversationen auf diesem Kanal beantworten soll. Legen Sie den kanalweiten Standard-Einstiegspunkt für den Kanal fest und benennen Sie den Agenten, den Sie in Schritt 2 erstellt haben:
curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'
Wiederholen Sie den Aufruf einmal pro Kanal — ein Kanal-Standard pro Kanal. Um einen Kanal ohne antwortenden Agenten zu belassen, rufen Sie DELETE /entry-points/channel-defaults?channel=whatsapp_web auf; um zu prüfen, ob die Einstiegspunkt-Hierarchie für das Konto aktiv ist, rufen Sie GET /entry-points/routing-status auf. Die ältere POST /channels/campaign-Zuordnung wird nur für Rollbacks beibehalten und nicht mehr für eingehendes Routing herangezogen. Siehe den Kanäle-Leitfaden für die anderen Kanaltypen und für den WhatsApp Business OAuth-Ablauf.
Schritt 4 — Kontakte importieren
Sobald ein Kanal aktiv ist, können Sie die Personen laden, die Sie erreichen möchten. Der Import-Endpunkt verarbeitet bis zu 500 Datensätze pro Aufruf. Jeder Datensatz benötigt eine phone_number im internationalen Format; alle weiteren Angaben sind optional. Datensätze mit ungültigen Nummern, nicht unterstützten Kanälen oder bereits vorhandenen Nummern werden übersprungen – jeder dieser Vorgänge wird mit Index und Grund gemeldet, sodass Sie nur die fehlgeschlagenen Einträge erneut versuchen können.
cURL
curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contacts": [
{ "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
{ "phone_number": "+12025551235", "first_name": "Bob" }
],
"defaultChannel": "whatsapp_web"
}'
JavaScript
const res = await fetch(`${BASE}/contacts/import`, {
method: "POST",
headers,
body: JSON.stringify({
contacts: [
{ phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
{ phone_number: "+12025551235", first_name: "Bob" },
],
defaultChannel: "whatsapp_web",
}),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);
Python
res = requests.post(
f"{BASE}/contacts/import",
headers=HEADERS,
json={
"contacts": [
{"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
{"phone_number": "+12025551235", "first_name": "Bob"},
],
"defaultChannel": "whatsapp_web",
},
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")
Die Antwort zeigt Ihnen genau an, was passiert ist:
{
"success": true,
"imported": 2,
"contact_ids": ["contactId1", "contactId2"],
"skipped": []
}
Informationen zur Erstellung einzelner Kontakte, zum Auflisten/Suchen, zu Listen, Tags und benutzerdefinierten Feldern finden Sie im Leitfaden für Kontakte.
Schritt 5 — Nachrichten senden und lesen
Eine Nachricht senden
Der einfachste Versand ist kanalunabhängig: Geben Sie die Identität des Kontakts und den Nachrichtentext an, und die Plattform stellt die Nachricht über den Kanal zu, auf dem sich der Kontakt befindet. Sie können die Zielgruppe nach contact_id oder nach channel plus dem passenden Identitätsfeld (phone_number für WhatsApp/WhatsApp Web/SMS, instagram_id für Instagram usw.) bestimmen.
cURL
curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp_web",
"phone_number": "+12025551234",
"body": "Hi Ann! Thanks for reaching out."
}'
JavaScript
const res = await fetch(`${BASE}/contacts/send`, {
method: "POST",
headers,
body: JSON.stringify({
channel: "whatsapp_web",
phone_number: "+12025551234",
body: "Hi Ann! Thanks for reaching out.",
}),
});
const { message_id } = await res.json();
Python
res = requests.post(
f"{BASE}/contacts/send",
headers=HEADERS,
json={
"channel": "whatsapp_web",
"phone_number": "+12025551234",
"body": "Hi Ann! Thanks for reaching out.",
},
)
message_id = res.json()["message_id"]
Die Zustellung erfolgt asynchron – ein 201 bedeutet, dass die Nachricht akzeptiert und in die Warteschlange eingereiht wurde, aber noch nicht zugestellt ist. (Kontakte mit aktiviertem „Nicht stören“-Modus oder privatem Modus werden mit einem 422 abgelehnt.)
{
"success": true,
"message_id": "aB3dE5fG7hI9jK1lM2nO",
"contact_id": "contact123",
"channel": "whatsapp_web"
}
Eine Unterhaltung lesen
Um Nachrichten abzurufen, listen Sie diese nach Kontakt auf, beginnend mit der neuesten, unter Verwendung von Cursor-Pagination. Übergeben Sie den next_cursor aus einer Antwort als cursor für die nächste, um den Verlauf rückwärts zu durchlaufen.
curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"
res = requests.get(
f"{BASE}/contacts/contact123/messages",
headers=HEADERS,
params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
print(msg)
next_cursor = page["next_cursor"] # pass back as ?cursor= for the next page
Sie können auch nach Inhaltstyp (?filter=text|media|tool_use) oder Richtung (?direction=inbound|outbound) filtern. Der Leitfaden für Nachrichten behandelt Medienanhänge, das Markieren von Nachrichten als gelesen sowie die sitzungsbezogenen Nachrichtenansichten.
Fragen Sie Antworten nicht per Polling ab. Das Auflisten von Nachrichten in einem Zeitintervall funktioniert zwar, verschwendet jedoch Anfragen und verursacht Verzögerungen. Verwenden Sie für eingehende Nachrichten stattdessen Webhooks – das ist Schritt 7.
Schritt 6 — Analysen lesen
Sobald Nachrichten fließen, liefert die Analyse-Zusammenfassung aggregierte Zählungen über einen Datumsbereich: gesendet, zugestellt, gelesen, beantwortet, gebucht, Kontakte erstellt sowie Credits verbraucht/aufgeladen. Sie erhalten sowohl Bereichssummen als auch eine mit Nullen gefüllte tägliche Datenreihe – perfekt für ein Dashboard-Diagramm. Optional können Sie dies mit campaign_id auf eine einzelne Kampagne eingrenzen (die Beispiele unten verwenden eine Platzhalter-Kampagnen-ID, abc123campaign); lassen Sie den Parameter weg, um kontoweite Summen zu erhalten.
curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"
const params = new URLSearchParams({
from: "2026-05-01",
to: "2026-05-31",
campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();
res = requests.get(
f"{BASE}/analytics/summary",
headers=HEADERS,
params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]
Der Standardbereich umfasst die letzten 30 Tage und ist auf 366 Tage begrenzt. Für detaillierte Nutzungsdatensätze pro Credit und KI-Kostenaufschlüsselungen siehe den Analyse-Leitfaden.
Schritt 7 — Webhooks für Echtzeit-Ereignisse abonnieren
Polling ist für ein schnelles Skript in Ordnung, aber eine echte Integration sollte Push-basiert sein. Webhooks ermöglichen es der Plattform, Ihren Server in dem Moment aufzurufen, in dem etwas passiert – ein neuer Kontakt, eine Antwort, ein gebuchter Termin, ein abgeschlossener Chat.
Ermitteln Sie zunächst die genauen Ereignisnamen, die Sie abonnieren können:
curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"
{
"success": true,
"events": [
"Contact Created",
"Human Alerted",
"Appointment Booked",
"Replies",
"New Message",
"Chat Concluded",
"Task Created",
"Daily Summary Created"
]
}
Erstellen Sie dann ein Abonnement, das auf eine HTTPS-URL auf Ihrem Server verweist. Verwenden Sie die exakten Ereignis-Strings aus dem obigen Aufruf.
cURL
curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Lead updates hook"
}'
JavaScript
const res = await fetch(`${BASE}/webhooks`, {
method: "POST",
headers,
body: JSON.stringify({
url: "https://hooks.example.com/incoming",
subscribed_to: ["Contact Created", "Replies"],
name: "Lead updates hook",
}),
});
const { webhook_id } = await res.json();
Python
res = requests.post(
f"{BASE}/webhooks",
headers=HEADERS,
json={
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Lead updates hook",
},
)
webhook_id = res.json()["webhook_id"]
{
"success": true,
"webhook_id": "1",
"webhook": {
"id": "1",
"name": "Lead updates hook",
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"subscribed_to_tags": [],
"created_at": "2026-06-09T12:00:00.000Z"
}
}
Die URL muss HTTPS verwenden und öffentlich erreichbar sein. Von nun an empfängt Ihr Server für jedes abonnierte Ereignis einen POST-Request. Sie können eine Testzustellung senden, den Status eines Abonnements überprüfen und ein Abonnement reaktivieren, das nach wiederholten Fehlern automatisch deaktiviert wurde – siehe den Webhooks-Leitfaden und die Seite Webhooks auf Integrationsebene für Payload-Formate und Verifizierung.
Alles zusammengefasst
Hier ist der gesamte Ablauf auf einen Blick:
| Schritt | Ziel | Wichtiger Aufruf |
|---|---|---|
| 1 | Authentifizieren | GET /health |
| 2 | Assistent erstellen + anpassen | POST /agents, PUT /agents/{id}/bot-config, PUT /agents/{id}/active-hours |
| 3 | Kanal verbinden und weiterleiten | POST /channels/whatsapp-web/connections → QR-Code abrufen + Status → PUT /entry-points/channel-defaults |
| 4 | Kontakte laden | POST /contacts/import |
| 5 | Senden & lesen | POST /contacts/send, GET /contacts/{id}/messages |
| 6 | Messen | GET /analytics/summary |
| 7 | In Echtzeit reagieren | POST /webhooks |
Ein minimaler Wrapper besteht nur aus diesen sieben Aufrufen, die in Ihre eigene Benutzeroberfläche eingebunden sind. Von dort aus können Sie je nach Bedarf die ressourcenspezifischen Leitfäden hinzuziehen:
- Kampagnen · Kontakte · FAQs · Nachrichten · Termine
- Kanäle · Vorlagen · Analysen · Webhooks · API-Schlüssel
- Neu hier? Erste Schritte · Authentifizierung · Fehler & Paginierung
Stuck on something this guide does not cover? Email hi@youraiconnector.com.