EchoHub API Guide 2026: Voice- und Chat-Agenten per REST-API in Ihre Software einbinden

Kurz gesagt: Die EchoHub API ist die REST-Schnittstelle von EchoCall unter https://hub.echocall.de/api/v1. Mit ihr legen Sie Voice- und Chat-Agenten aus Ihrer eigenen Software an, lesen Gespräche und Auswertungen, buchen Rufnummern und empfangen Ereignisse per signiertem Webhook. Sie melden sich mit einem API-Key als Bearer-Token an, den Sie im Developer-Bereich des EchoHub erzeugen. Die vollständige Referenz ist öffentlich, auch als OpenAPI-Datei. [1][2]

Wir haben diesen Beitrag im Oktober 2026 neu geschrieben. Die alte Fassung versprach fertige Anbindungen an ERP-Systeme und Telefonanlagen sowie eine Stimmungsanalyse in Echtzeit. Das konnten wir in der API-Referenz nicht belegen, deshalb ist es raus. Jeder Endpunkt und jedes Feld in diesem Text steht in der veröffentlichten Referenz, Version 1.13.0. [2]

Was die EchoHub API ist

Der EchoHub ist die Oberfläche, in der EchoCall-Kunden ihre Agenten bauen. Die API bietet dieselben Bausteine für Programme statt für Menschen. Sie folgt dem REST-Prinzip, spricht JSON und ist als OpenAPI-3.1-Datei beschrieben. Aus dieser Datei erzeugen Sie mit einem üblichen Generator einen Client in Ihrer Programmiersprache, oder Sie importieren sie in Postman oder Insomnia.

Ein erster Test geht ohne Schlüssel:

curl https://hub.echocall.de/api/v1/health

Die Antwort enthält den Status und die laufende Version. Am 6. Oktober 2026 war das "version":"1.13.0". [3]

Wann Sie die API brauchen, und wann nicht

Viele Anbindungen brauchen keine Zeile Code. Google Calendar, Outlook, HubSpot, Salesforce, Zendesk und weitere Dienste verbinden Sie im EchoHub als Integration. Der Agent nutzt sie dann im Gespräch als Werkzeug: Er bucht einen Termin, sucht einen Kontakt oder legt ein Ticket an. Für eigene Systeme ohne fertige Integration gibt es eigene Webhooks als Werkzeug. Wie das ohne Programmierung geht, zeigt der Beitrag KI-Agent erstellen ohne Programmierung.

Die API lohnt sich in drei Fällen:

1. Sie bauen EchoCall in Ihr eigenes Produkt ein. Ein Praxisverwaltungssystem, ein Shop-Backend oder ein Intranet soll Agenten anlegen und Gespräche anzeigen, ohne dass Ihre Nutzer den EchoHub öffnen.
2. Sie verarbeiten Ereignisse automatisch weiter. Nach jedem Chat soll ein Datensatz in Ihrem Data Warehouse landen, oder ein neues Ticket soll in Ihrem Helpdesk auftauchen.
3. Sie verkaufen Agenten an eigene Kunden. Agenturen, Hoster und Systemhäuser legen Kundenkonten an, verteilen Guthaben und rechnen ab. Das WHMCS-Modul und das White-Label-Portal von EchoCall nutzen genau diese Endpunkte.

Die Endpunkte der EchoCall API im Überblick

Die Referenz umfasst in Version 1.13.0 genau 130 Pfade. [2] Die wichtigsten Gruppen:

Dazu kommen Tickets, Integrationen, Stimmen, Sprachen, Benachrichtigungen und Kampagnen für Anruflisten unter /batch-calling/campaigns.

API-Key erstellen: Authentifizierung und Scopes

Den Schlüssel erzeugen Sie im EchoHub im Bereich Developer unter hub.echocall.de/developer. Sie vergeben einen Namen und können zwei Sperren setzen: eine Liste erlaubter IP-Adressen und eine Liste erlaubter Domains, die über die Header Origin und Referer geprüft wird. Anfragen von anderswo lehnt die API mit dem Status 403 ab. Der vollständige Schlüssel wird nur einmal angezeigt, direkt nach dem Anlegen. Im selben Bereich können Sie Schlüssel widerrufen und die Anfrageprotokolle Ihrer Schlüssel einsehen.

Der Schlüssel beginnt mit eck_live_, gefolgt von 64 Hexadezimalzeichen, und geht als Bearer-Token in jede Anfrage:

curl -H "Authorization: Bearer $ECHOCALL_API_KEY" "https://hub.echocall.de/api/v1/agents?page=1&perPage=20"

Drei Punkte, die in der Praxis Ärger sparen:

• Es gibt keinen Testmodus. Jeder Schlüssel arbeitet auf Ihrem echten Konto. Ein Nummernkauf über die API kostet echtes Guthaben. Nehmen Sie für Experimente einen eigenen Schlüssel und rufen Sie nur lesende Endpunkte auf, bis Ihr Code steht.
• Der Schlüssel gehört auf den Server. Nie in JavaScript im Browser, nie in eine App, nie in ein Git-Repository. Wer ihn hat, handelt in Ihrem Namen.
• Jede Operation verlangt einen Scope. Die Referenz nennt ihn je Endpunkt, etwa read:agents oder write:webhooks. Schlüssel aus dem Developer-Bereich bekommen alle Scopes. Fehlt einer, antwortet die API mit 403 insufficient_permissions und nennt den benötigten Scope. Die Partner-Endpunkte unter /resellers und /provisioning setzen zusätzlich ein Reseller-Konto voraus.

Erste Anfragen: Agent anlegen, Wissen hinzufügen, testen

Ein Voice-Agent braucht zwei Pflichtfelder: name und language als Sprachcode nach ISO 639-1. Alles andere hat Standardwerte. Legen Sie den Inhalt in eine Datei agent.json:

{
  "name": "Empfang Praxis Beispiel",
  "language": "de",
  "firstMessage": "Guten Tag, hier spricht der KI-Assistent der Praxis Beispiel. Wie kann ich helfen?",
  "systemPrompt": "Du nimmst Terminwünsche entgegen und beantwortest Fragen zu Öffnungszeiten und Anfahrt.",
  "saveCallAudio": false,
  "retentionDays": 30
}

curl -X POST https://hub.echocall.de/api/v1/agents -H "Authorization: Bearer $ECHOCALL_API_KEY" -H "Content-Type: application/json" -d @agent.json

Die Antwort enthält die id des neuen Agenten, den Namen, die Sprache, den Status und den Zeitpunkt der Anlage. Achten Sie auf die erste Nachricht: Sie nennt das Unternehmen und sagt, dass eine KI spricht. Bei Telefon-Agenten schreiben Sie diesen Hinweis selbst in die Begrüßung. Warum das seit August 2026 Pflicht ist, erklärt der Beitrag zum EU AI Act und der KI-Hinweispflicht.

Danach bekommt der Agent sein Wissen. Der einfachste Weg ist eine Seite Ihrer Website:

curl -X POST https://hub.echocall.de/api/v1/agents/AGENT_ID/knowledge -H "Authorization: Bearer $ECHOCALL_API_KEY" -H "Content-Type: application/json" -d '{"type":"url","url":"https://www.example.de/leistungen"}'

Ändert sich die Seite, lesen Sie die Quelle über /agents/{agentId}/knowledge/{knowledgeId}/refresh neu ein.

Zum Testen müssen Sie keine Nummer buchen. POST /agents/{agentId}/preview öffnet einen Testanruf im Browser. Die Antwort liefert einen WebSocket-Pfad auf dem API-Host, eine Höchstdauer und eine Frist, in der der Pfad einmal geöffnet werden darf. [2] So bauen Sie in Ihrer eigenen Oberfläche einen Knopf, mit dem Ihre Nutzer den Agenten anhören, bevor er echte Anrufe annimmt.

Chat-Agenten legen Sie über POST /chatbots an. Pflicht ist nur der Name. Die Antwort enthält neben der id eine öffentliche Adresse des Chats. Auf Ihre Website kommt der Agent mit einer Zeile:

<script src="https://cdn.echocall.de/widget.js" data-id="CHATBOT_ID" async></script>

Webhooks: Ereignisse empfangen und Signatur prüfen

Statt regelmäßig nachzufragen, lassen Sie sich benachrichtigen. Sie registrieren eine HTTPS-Adresse und wählen die Ereignisse:

curl -X POST https://hub.echocall.de/api/v1/webhooks -H "Authorization: Bearer $ECHOCALL_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://api.example.de/echocall/events","events":["conversation.closed","ticket.created"]}'

Die Antwort enthält ein secret. Speichern Sie es sofort, die API gibt es nie wieder aus. [2] Diese Ereignisse stehen im Katalog, den GET /webhooks/events liefert:

Mit "*" abonnieren Sie alle Ereignisse. Jede Zustellung ist ein POST mit den Feldern id, event, createdAt und data sowie dem Header X-EchoCall-Signature im Format t=<Unix-Zeit>,v1=<Hex>. Der Wert v1 ist ein HMAC-SHA256 über t, einen Punkt und den rohen Request-Body, berechnet mit Ihrem Secret. [2][4]

Prüfen Sie jede Zustellung, bevor Sie ihr glauben. Ein Beispiel in Python:

import hashlib
import hmac
import time


def verify(secret, header, raw_body, tolerance=300):
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts = int(parts.get("t", "0"))
    now = int(time.time())
    if ts + tolerance < now or ts > now + tolerance:
        return False
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Drei Regeln dazu. Rechnen Sie über den rohen Body, bevor ein Framework das JSON umformt. Vergleichen Sie in konstanter Zeit, wie es hmac.compare_digest tut. [5] Und verwerfen Sie Zustellungen mit zu alter Zeitangabe, damit niemand eine abgefangene Nachricht später wiederholt. Die Referenz zeigt dieselbe Prüfung in Node.js. [1]

Zur Zustellung selbst: Ihr Endpunkt muss innerhalb von 10 Sekunden mit einem 2xx-Status antworten. Sonst versucht es EchoCall nach 1, 5 und 30 Sekunden erneut. Nach 25 Fehlschlägen in Folge wird der Endpunkt abgeschaltet und erst wieder beliefert, wenn Sie ihn per PATCH /webhooks/{id} einschalten. POST /webhooks/{id}/test schickt jederzeit eine einzelne Probe ohne Wiederholung. [2]

Daraus folgen drei Bauregeln. Nehmen Sie Zustellungen sofort an und verarbeiten Sie sie danach in einer Warteschlange. Merken Sie sich die id jedes Ereignisses, denn eine Wiederholung trägt dieselbe id und darf nicht doppelt verbucht werden. Und gleichen Sie in festen Abständen über GET /conversations ab. Webhooks sind schnell, aber ein Ereignis kann verloren gehen, etwa wenn Ihr Server gerade neu startet. Der Abgleich fängt das auf.

Fehlercodes, Rate Limits und Pagination

Jeder Fehler kommt im selben Umschlag:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {}
  }
}

Verzweigen Sie im Code nach code, nicht nach dem Text in message. Die Texte können sich ändern, die Codes sind die Schnittstelle. [2]

Das Rate Limit gilt je Schlüssel und Sekunde, standardmäßig 500 Anfragen. Jede Antwort trägt die Header X-RateLimit-Limit und X-RateLimit-Remaining. Wer darüber liegt, bekommt 429 mit Retry-After: 1. Strenger ist das Anlegen neuer Kundenkonten über /provisioning/create: höchstens 10 je Minute und Schlüssel. [2]

Listen sind seitenweise. page beginnt bei 1, perPage geht bis höchstens 100. Die Antwort enthält ein Objekt pagination. Lesen Sie so lange weiter, bis eine Seite weniger Einträge liefert, als Sie angefordert haben.

Voice-API mit DSGVO-Vertrag: Datenschutz per API steuern

Wer eine Voice-API für Kundengespräche einsetzt, verarbeitet personenbezogene Daten im Auftrag. Art. 28 DSGVO verlangt dafür einen Vertrag mit dem Auftragsverarbeiter. [6] EchoCall stellt den Auftragsverarbeitungsvertrag auf der Seite AVV bereit, die Server stehen in Rechenzentren von IONOS in Frankfurt und Karlsruhe. Mehr dazu auf der Datenschutzseite.

Wichtiger als das Papier sind die Einstellungen, die Sie je Agent setzen. Die API bietet dafür drei Felder: [2]

• saveCallAudio entscheidet, ob die Tonaufnahme gespeichert wird. Standard ist false.
• retentionDays legt fest, wie lange Gespräche aufbewahrt werden. Standard sind 30 Tage, -1 heißt dauerhaft.
• zeroPiiRetention schaltet den Zero-PII-Modus ein, für Branchen, in denen keine personenbezogenen Gesprächsdaten liegen bleiben sollen.

Setzen Sie diese Felder bewusst, statt sich auf Standards zu verlassen. Und schreiben Sie in Ihr Verzeichnis der Verarbeitungstätigkeiten, welche Ereignisse Ihr Webhook-Empfänger speichert. Was er speichert, liegt in Ihrer Verantwortung, nicht mehr bei EchoCall.

API für Reseller und White Label

Agenturen und Hoster, die Agenten unter eigener Marke verkaufen, brauchen ein Reseller-Konto. Dann stehen zwei Gruppen zusätzlich bereit.

Kunden verwalten. POST /resellers/customers legt ein Kundenkonto an, Pflicht ist nur die E-Mail-Adresse. Weitere Endpunkte verteilen Guthaben, ordnen Rufnummern zu, sperren und entsperren Kunden und liefern Rechnungen als PDF.

Im Namen eines Kunden handeln. Mit dem Header X-EchoCall-Customer: <customerId> arbeiten dieselben Aufrufe, etwa GET /agents oder POST /chatbots, auf dem Konto dieses Kunden. Solange der Header gesetzt ist, sind die Reseller-Endpunkte gesperrt. Das verhindert, dass ein Fehler in Ihrer Kundenansicht Partnerdaten verändert.

Abrechnungssysteme anbinden. /provisioning bildet den Lebenszyklus eines Produkts ab: anlegen, sperren, entsperren, kündigen, Paket wechseln. Das WHMCS-Plugin für KI Voice- und Chat-Agenten nutzt genau diese Endpunkte. Wer ein eigenes Kundenportal will, ohne es selbst zu bauen, findet im Open-Source White-Label-Portal eine fertige Oberfläche auf derselben API. Die Konditionen für Partner stehen auf der Seite PartnerNet.

Checkliste vor dem Livegang

1. Der Schlüssel liegt nur auf dem Server, idealerweise mit IP-Sperre.
2. Jede Integration hat einen eigenen Schlüssel, damit Sie einen einzelnen widerrufen können.
3. Fehler werden nach code behandelt, 429 und 5xx mit Pause wiederholt.
4. Der Webhook-Empfänger prüft Signatur und Zeitfenster und erkennt Doppelte an der id.
5. Ein regelmäßiger Abgleich über GET /conversations fängt verlorene Ereignisse auf.
6. Audio, Aufbewahrung und Zero-PII sind je Agent bewusst gesetzt.
7. Die erste Nachricht jedes Telefon-Agenten enthält den KI-Hinweis.

Häufige Fragen

Wo finde ich die Dokumentation der EchoCall API?

Die interaktive Referenz liegt unter hub.echocall.de/api/v1/docs, die maschinenlesbare OpenAPI-Datei unter hub.echocall.de/api/v1/docs/openapi.json. Beide sind ohne Anmeldung erreichbar. Die Referenz beschreibt jeden Endpunkt mit Feldern, Beispielen, Fehlercodes und dem nötigen Scope.

Gibt es eine Sandbox oder einen Testmodus?

Nein. Jeder API-Key arbeitet auf Ihrem echten Konto, kostenpflichtige Aktionen wie ein Nummernkauf belasten Ihr Guthaben. Testen Sie mit lesenden Endpunkten und mit POST /agents/{agentId}/preview, das einen Testanruf im Browser öffnet, ohne dass Sie eine Nummer brauchen.

Wie authentifiziere ich mich bei der API?

Mit einem Schlüssel aus dem Developer-Bereich des EchoHub, gesendet als Authorization: Bearer eck_live_.... Andere Formen akzeptiert die API nicht. Optional binden Sie den Schlüssel an bestimmte IP-Adressen oder Domains.

Welche Webhook-Ereignisse gibt es?

Beendete Telefongespräche, eingehende und ausgehende Chat-Nachrichten, geschlossene Gespräche sowie neue und geänderte Tickets. Jede Zustellung ist mit HMAC-SHA256 signiert, fehlgeschlagene Zustellungen werden nach 1, 5 und 30 Sekunden wiederholt.

Kann ich als Agentur Kundenkonten per API verwalten?

Ja, mit einem Reseller-Konto. Sie legen Kunden an, verteilen Guthaben, ordnen Rufnummern zu und handeln über den Header X-EchoCall-Customer im Namen eines Kunden. Für Abrechnungssysteme gibt es die Provisioning-Endpunkte, die auch das WHMCS-Modul nutzt.

Gibt es ein offizielles SDK?

Derzeit nicht. Aus der OpenAPI-Datei erzeugen Sie mit einem gängigen Generator einen typisierten Client für Ihre Sprache. Für viele Fälle reicht ein schlanker HTTP-Client, denn alle Anfragen folgen demselben Muster.

Quellen

Die Quellen sind englischsprachig, sofern nicht anders angegeben.

1. EchoCall API Reference, interaktive Dokumentation: hub.echocall.de/api/v1/docs
2. EchoCall OpenAPI-Spezifikation, Version 1.13.0: hub.echocall.de/api/v1/docs/openapi.json
3. EchoCall API, Health-Endpunkt mit Versionsangabe: hub.echocall.de/api/v1/health
4. RFC 2104, HMAC: Keyed-Hashing for Message Authentication: rfc-editor.org
5. Python-Dokumentation, Modul hmac mit compare_digest: docs.python.org
6. Verordnung (EU) 2016/679 (DSGVO), Art. 28 Auftragsverarbeiter (deutsch): eur-lex.europa.eu

Alle Links wurden am 6. Oktober 2026 geprüft. Dieser Beitrag ist keine Rechtsberatung.

Weiterlesen

• WHMCS Plugin: KI Voice & Chat Agents als Hosting-Zusatzprodukt verkaufen
• White Label KI-Agenten Plattform 2026: das Open-Source-Portal
• KI-Chatbot auf WordPress mit dem EchoCall Plugin
• KI und Datensicherheit 2026: Der umfassende DSGVO-Leitfaden für Voice Agents