# 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: 1. Authentifizierung mit einem API-Schlüssel 2. Erstellen eines KI-Agenten und Konfigurieren seines Assistentenverhaltens 3. Verbinden eines Messaging-Kanals (wir verwenden WhatsApp Web als Beispiel) und Zuweisen an den Agenten 4. Importieren von Kontakten 5. Senden und Lesen von Nachrichten 6. Lesen von Analysedaten 7. 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 `403` zurück. Siehe [API-Zugriff](../integrations/api-access.md), um zu bestätigen, dass er aktiviert ist, und [Authentifizierung](authentication.md) 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](../integrations/api-access.md). 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** ```bash curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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](errors-and-pagination.md) 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 `429` zurü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** ```bash 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** ```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** ```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: ```json { "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: ```bash 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](faqs.md). > **Legacy: klassische Kampagnen.** Konten, die noch über eine **Kampagnen**-Seite verfügen, erstellen dasselbe Assistentenverhalten stattdessen für eine Kampagne (`POST /campaigns` mit einem `type`- und einem `bot`-Objekt, dann `PUT /campaigns/{campaignId}/bot-config`). Die vollständige Liste der Kampagnenfelder und Lebenszyklus-Steuerungen finden Sie im [Kampagnen-Leitfaden](campaigns.md). 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: ```bash 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](channels.md) 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. ```bash 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" }' ``` ```javascript await fetch(`${BASE}/channels/whatsapp-web/connections`, { method: "POST", headers, body: JSON.stringify({ phone_number: "+15551230000" }), }); ``` ```python 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. ```bash curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY" ``` ```json { "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 `` 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. ```python 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) ``` ```javascript 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: ```bash 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](channels.md) 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** ```bash 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** ```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** ```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: ```json { "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](contacts.md). --- ## 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** ```bash 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** ```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** ```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.) ```json { "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. ```bash curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY" ``` ```python 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](messages.md) 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. ```bash curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY" ``` ```javascript 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(); ``` ```python 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](analytics.md). --- ## 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: ```bash curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY" ``` ```json { "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** ```bash 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** ```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** ```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"] ``` ```json { "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](webhooks.md) und die Seite [Webhooks](../integrations/webhooks.md) 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](campaigns.md) · [Kontakte](contacts.md) · [FAQs](faqs.md) · [Nachrichten](messages.md) · [Termine](appointments.md) - [Kanäle](channels.md) · [Vorlagen](templates.md) · [Analysen](analytics.md) · [Webhooks](webhooks.md) · [API-Schlüssel](api-keys.md) - Neu hier? [Erste Schritte](getting-started.md) · [Authentifizierung](authentication.md) · [Fehler & Paginierung](errors-and-pagination.md) Stuck on something this guide does not cover? Email [hi@youraiconnector.com](mailto:hi@youraiconnector.com).