REST-Anleitung

KI-Anruf per REST starten — ein POST, ein Webhook, ein Transkript.

Ihr CRM, Ticketing-Tool, Ihre Marketing-Automation oder Ihr Backend-Job sendet einen einzigen HTTP-POST. Die CodeB-Plattform setzt die Zielnummer auf die Whitelist, wählt sie über den konfigurierten SIP-Trunk an und verbindet eine Live-Voice-AI-Session, die Ihrem System-Prompt folgt. Wenn der Anruf endet, erhält Ihr Webhook-Empfänger einen signierten POST mit dem Ergebnis und einem Transkript-Dateinamen, den Sie bei Bedarf abrufen können. Ende zu Ende — in jeder Sprache unter zwanzig Codezeilen.

REST / JSON Bearer-Auth HMAC-signierte Webhooks curl / Python / Node.js EU-gehostet Mandantenfähig Programmierbare Retries

Was Sie bauen

Eine Vier-Schritt-Integration: Token holen, Anruf posten, Webhook empfangen, Transkript abrufen. Das Diagramm zeigt, wo jede Komponente lebt. Ihr Code spricht immer nur mit einem Host (Ihrem CodeB-Tenant) über reines HTTPS — kein SIP, kein WebRTC, keine Medien-Plumbing auf Ihrer Seite.

IHR SYSTEM CRM / Scheduler / Backend Entscheidet wen, wann und was die KI sagen soll CODEB-TENANT /api.ashx/v1/calls Bearer-authentifiziertes REST. Liefert callId sofort zurück. KONTAKT Telefon klingelt (PSTN/SIP) Voice-KI grüsst, spricht, leitet weiter oder beendet. WEBHOOK-PUSH outbound-ai.finished HMAC-signierter POST an Sie mit Status, Dauer, Grund. IHR EMPFÄNGER CRM-Datensatz aktualisieren Signatur prüfen, Ergebnis loggen, nächsten Schritt auslösen. TRANSKRIPT-ABRUF GET /v1/transcripts/… Plain text + JSON-Sidecar mit Zeitstempeln pro Sprechakt. 1. POST /v1/calls 2. SIP-Wählversuch 3. Anruf endet 4. Webhook-POST 5. GET /v1/transcripts/<Datei> Durchgezogene amber-farbene Pfeile: ausgehend von Ihrem Code. Gestrichelt cyan: Plattform pusht zu Ihnen.

Voraussetzungen

Ein CodeB-Tenant

Beliebige von Ihnen kontrollierte Domain: https://phone.ihrtenant.de. Selbst-gehostet oder auf einem CodeB-betriebenen Tenant. Mandantenisolation ist pro Domain.

Ein Bearer-Token

Entweder ein OIDC-Access-Token (von /oidc.ashx/token) oder ein ak_-API-Schlüssel aus dem Tenant-Admin. Beide funktionieren auf jedem Endpunkt dieser Seite.

Ein konfigurierter SIP-Trunk

Bereits vorhanden, wenn Sie normale Anrufe tätigen / empfangen können. Die Plattform wählt den Trunk über Ihre Outbound-Routing-Regeln — keine Trunk-Wahl pro Anruf nötig.

Ein Sprach-Engine-API-Key

Bringen Sie Ihren eigenen Voice-AI-Engine-Key mit. Sie bringen Ihren eigenen Key mit; die Plattform speichert ihn nicht über den Anruf hinaus.

Einwilligung des Empfängers

Ausgehende KI-Anrufe sind reguliert. Bestätigen Sie das Opt-in (TCPA / DSGVO / ePrivacy / lokale Vorschriften). Die Plattform ist Transport — die Einwilligung liegt bei Ihnen.

Ein Webhook-Empfänger (optional)

Ein öffentlicher HTTPS-Endpoint, der POST annimmt. Ohne ihn findet der Anruf trotzdem statt — Sie pollen dann GET /v1/calls/{id}.

Schritt 1 — Bearer-Token holen

Überspringen Sie diesen Schritt, wenn Sie bereits einen ak_-API-Schlüssel aus dem Tenant-Admin haben — verwenden Sie ihn direkt als Authorization: Bearer ak_ihrkeyhier. Für interaktive Flows tauschen Sie Benutzername/Passwort gegen ein kurzlebiges OIDC-Access-Token:

# Benutzername + Passwort gegen kurzlebiges OIDC-Access-Token tauschen.
TOKEN=$(curl -s -X POST "https://phone.ihrtenant.de/oidc.ashx/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=alice&password=IHR_PASSWORT&scope=openid" \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")

echo "$TOKEN"
Tipp. Für Machine-to-Machine-Jobs — nächtlicher Cron, Webhook-Responder, CRM-Workflow — im Tenant-Admin einmal einen ak_-API-Schlüssel anlegen und den Token-Dance überspringen. Es ist derselbe Bearer-Header auf jedem Aufruf.

Schritt 2 — Anruf posten

Senden Sie einen einzigen JSON-Body an POST /api.ashx/v1/calls mit Zielnummer, Anweisungen für die KI und dem E-Mail-Empfänger für das Transkript. Die Antwort kommt sofort; der eigentliche Wählversuch läuft asynchron.

Request-Felder

FeldTypPflichtHinweise
phonestringjaE.164, z. B. +4915157610183. Nummern werden vor dem Whitelist-Eintrag normalisiert.
displayNamestringneinCaller-ID-Label / SIP-From-Display. Standard: phone.
emailstringjaEmpfänger für Transkript + Ergebnis-Mail nach Anrufende.
systemPromptstringjaKlartext-Anweisungen an die KI, oder ein Slug eines gespeicherten Tenant-Prompts (z. B. reminder).
apiKeystringjaVoice-AI-Engine-Key. Pro Anruf verwendet — nicht gespeichert.
modelstringneinEngine-Model-ID. Standard: Tenant-Konfiguration.
voicestringneinz. B. Aoede, Charon. Standard Aoede.
languagestringneinBCP-47-Tag, z. B. en-US, de-DE. Standard en-US.
maxSecondsintneinHarte Obergrenze, 10–3600. Standard 300.
retriesintnein0–10. Wie viele erneute Versuche bei Nicht-Antwort / besetzt. Standard 0.
retryDelayMinutesintnein1–1440. Abstand zwischen Wiederholungen. Standard 5.
scheduleAtUtcstringneinISO-8601 UTC. Ohne Angabe sofort wählen. Für Kampagnen mit zukünftiger Zeit.

Beispiel — Terminerinnerung

curl -X POST https://phone.ihrtenant.de/api.ashx/v1/calls \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone":        "+4915157610183",
    "displayName":  "Erinnerung",
    "email":        "ops@ihrunternehmen.example",
    "systemPrompt": "Du rufst Alex an, um den Zahnarzttermin morgen um 14:00 zu bestaetigen. Sei kurz und freundlich. Wenn JA, verabschiede dich. Wenn NEIN, biete denselben Termin naechste Woche an.",
    "apiKey":       "IHR_AI_API_KEY",
    "voice":        "Aoede",
    "language":     "de-DE",
    "maxSeconds":   180,
    "retries":      2,
    "retryDelayMinutes": 10
  }'

Antwort

{
  "ok":              true,
  "callId":          "oac-0123456789ab",
  "tenant":          "phone.ihrtenant.de",
  "whitelistAdded":  true,
  "whitelistError":  null,
  "bridgeReply":     "{...}"
}

Speichern Sie die callId auf Ihrem Datensatz. Sie erscheint im Webhook, in GET /v1/calls/{id} und im Transkript-Dateinamen (outbound-ai-YYYYMMDD-HHMMSS-<callId>.txt) wieder.

Schritt 3 — Webhook empfangen

Sekunden nach Anrufende erhält Ihre abonnierte Webhook-URL zwei HMAC-signierte POSTs: outbound-ai.finished mit dem Ergebnis und (falls Aufzeichnung oder Transkription aktiviert war) transcript.saved mit dem Pfad. Prüfen Sie die Signatur immer zuerst.

X-CodeB-Signature prüfen

import hmac, hashlib, os
from flask import Flask, request, abort

WEBHOOK_SECRET = os.environ["CODEB_WEBHOOK_SECRET"].encode()
app = Flask(__name__)

def verify(raw_body: bytes, sig_header: str) -> bool:
    expected = hmac.new(WEBHOOK_SECRET, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, (sig_header or "").strip())

@app.post("/codeb/webhook")
def hook():
    raw = request.get_data()                        # Rohbytes, NICHT json()
    sig = request.headers.get("X-CodeB-Signature", "")
    if not verify(raw, sig):
        abort(401)
    evt = request.get_json()                        # jetzt sicher parsen
    if evt["type"] == "outbound-ai.finished":
        update_crm(evt["data"]["callId"], evt["data"]["status"])
    return ("", 204)

So sieht der Webhook-Body aus

{
  "type":      "outbound-ai.finished",
  "tenant":    "phone.ihrtenant.de",
  "timestamp": "2026-06-23T12:02:31.000Z",
  "data": {
    "callId":          "oac-0123456789ab",
    "phone":           "+4915157610183",
    "displayName":     "Erinnerung",
    "status":          "ended-success",
    "endedReason":     "finished",
    "durationSec":     145,
    "dispatchedAtUtc": "2026-06-23T12:00:00.000Z",
    "answeredAtUtc":   "2026-06-23T12:00:05.500Z",
    "endedAtUtc":      "2026-06-23T12:02:30.000Z",
    "transcriptPath":  "outbound-ai-20260623-120000-oac-0123456789ab.txt",
    "attempt":         1,
    "retriesLeft":     1
  }
}
Keine öffentliche URL? Webhook komplett überspringen. Pollen Sie GET /api.ashx/v1/calls/{id}, bis status einer von ended-success, ended-failed-final oder cancelled ist. Günstig, keine Infrastruktur, kein Signatur-Tanz.

Schritt 4 — Transkript abrufen

Für Analytik, Follow-up-Generierung oder Compliance-Archivierung holen Sie das Transkript nach Eintreffen des Webhooks. Die Plattform produziert pro Anruf zwei Artefakte: ein Klartext-Transkript (.txt) und eine strukturierte JSON-Sidecar (.json) mit Zeitstempeln, Rollen und Tool-Call-Records pro Sprechakt.

curl -H "Authorization: Bearer $TOKEN" \
  "https://phone.ihrtenant.de/api.ashx/v1/transcripts/outbound-ai-20260623-120000-oac-0123456789ab.txt"

Beispiel-Transkript (Klartext, eine Zeile pro Sprechakt):

[12:00:06] KI:    Hallo, hier ist Ihr Erinnerungsdienst. Spreche ich mit Alex?
[12:00:09] USER:  Ja, hier Alex.
[12:00:11] KI:    Kurze Erinnerung an Ihren Zahnarzttermin morgen um 14:00 Uhr.
                  Schaffen Sie den Termin?
[12:00:17] USER:  Ja, ich bin da.
[12:00:19] KI:    Wunderbar. Schönen Tag noch. Auf Wiederhören.

Wollen Sie auch Aufzeichnungen? Aktivieren Sie pro VNum oder pro Trunk die Audio-Aufzeichnung im Admin — eine Stereo-WAV landet in App_Data/<tenant>/recordings/YYYY/MM/DD/ mit einem JSON-Sidecar gleicher Metadaten. Volle Endpoint-Referenz auf der REST-API-Seite.

Häufige Muster

Terminerinnerungen

Ihr Buchungstool feuert den POST 24h vor jeder Buchung. KI bestätigt oder verschiebt. Ergebnis landet via Webhook wieder im Buchungsdatensatz.

Lead-Qualifizierung

Marketing-Automation feuert den POST Sekunden nach Formular-Submit. KI begrüsst, qualifiziert nach Skript und leitet (mit Einwilligung) an Vertrieb weiter.

Zahlungserinnerungen / Mahnungen

Buchhaltung bündelt morgens überfällige Forderungen, postet pro Schuldner einen Anruf. Tonlage über System-Prompt steuerbar. Transkript für den Audit-Trail archiviert.

Service-Follow-up-Umfragen

Ticketing-Tool postet eine Stunde nach Ticket-Close. KI stellt drei strukturierte Fragen. JSON-Transkript speist Ihr NPS-Dashboard.

Interne Mitarbeiterbenachrichtigung

On-Call / Outage-Tooling postet an die Nummer des Engineers. KI liest den Alert vor, bestätigt Acknowledgement, beendet. Günstig, sprachneutral, keine App nötig.

Mehrsprachige Kampagnen

Sprache pro Anruf wählen (de-DE, en-US, fr-FR, es-ES, …). Gleicher Endpoint, gleicher Flow, Voice + Prompt wechseln automatisch.

Hotellerie — Sensoren triggern Anrufe

Lärmmesser oder Rauchmelder in der Kurzzeit-Wohnung schlägt aus → Sensor-Plattform POSTet an Ihren Webhook → KI-Voice-Agent ruft den Gast in Sekunden an, nennt die Wohnung, zitiert den Schwellwert, bittet um Handlung. Praxisbeispiel auf hospitality.html.

Abbrechen, auflisten, inspizieren

Drei weitere Endpoints runden den Lebenszyklus ab:

Verb + PfadWas es tut
GET /api.ashx/v1/callsAktive + jüngste Anrufe listen. Filter nach status: scheduled,in-flight,ended-success usw. Paginierung mit limit + offset.
GET /api.ashx/v1/calls/{id}Ein Anruf — Status, Ergebnis, Transkript-Pfad, Versuchszähler, Retry-Budget.
POST /api.ashx/v1/calls/{id}/hangupGeplanten Anruf abbrechen oder laufenden beenden. Idempotent. Verwenden, wenn der Kontakt sich anderweitig gemeldet hat, bevor die KI angewählt hat.

Volle Request/Response-Form mit jedem Feld in der REST-API-Referenz.

Sicherheit & Compliance

  • Bearer-Auth auf jedem Aufruf. OIDC-Access-Tokens oder ak_-API-Schlüssel. Keine anonymen Endpoints, kein IP-Allowlisting für die REST-Oberfläche nötig.
  • HMAC-signierte Webhooks. X-CodeB-Signature ist HMAC-SHA256 des Rohbodys mit Ihrem Subscription-Secret. Vor dem Parsen prüfen. Secret jederzeit im Admin rotierbar.
  • Mandantenisolation. Jeder API-Key, jedes Token, jedes Transkript, jede Aufzeichnung und jeder CDR ist auf den ausstellenden Tenant-Host gescoped. Cross-Tenant-Reads werden im Dispatcher geblockt.
  • EU-gehostet, selbst-hostbar. Auf eigener Infrastruktur oder auf einem EU-Region-Tenant. Kein US-Transfer für Signalisierung, Medien, Transkripte oder Aufzeichnungen.
  • Einwilligung des Empfängers. Ausgehende KI-Anrufe sind in den meisten Jurisdiktionen reguliert (DSGVO / ePrivacy in der EU, TCPA in den USA, lokale Vorschriften). Die Plattform tätigt den Anruf, den Sie verlangen; Einwilligungs-Erhebung liegt bei Ihnen.
  • Auditierbar. Jeder Anruf hinterlässt einen CDR (Caller / Callee / Trunk / Ergebnis / Dauer) und ein optionales Transkript + Aufzeichnung für die Compliance-Aufbewahrung.

Bereit, Outbound-KI in einem Nachmittag zu liefern?

Kostenlosen CodeB-Tenant anlegen, Sprach-Engine-API-Key einfügen, den ersten POST feuern. Volle Referenz + jeder Endpoint auf dem API-Hub.

Häufige Fragen

Muss ich SIP, WebRTC oder Medienverarbeitung selbst einrichten?

Nein. Ihr Code spricht immer nur HTTPS mit einem Host (Ihrem CodeB-Tenant). Die Plattform tätigt den SIP-Anruf, hängt die KI-Session an, transcodiert Audio, kümmert sich um ICE und räumt beim Hangup auf. Sie senden einen JSON-POST und (optional) erhalten einen signierten Webhook.

Kann ich Anrufe in die Zukunft planen oder nur sofort wählen?

Beides. Ohne scheduleAtUtc wählt die Plattform sofort. Mit ISO-8601-UTC-Zeitstempel reiht sie den Anruf ein und feuert ihn zu diesem Zeitpunkt. In beiden Fällen genau ein POST aus Ihrem Code.

Wie authentifiziere ich mich an der API?

Zwei Möglichkeiten, beide Bearer-Tokens. Entweder ein kurzlebiges OIDC-Access-Token von /oidc.ashx/token oder ein langlebiger ak_-API-Schlüssel, einmal im Tenant-Admin angelegt. Derselbe Authorization-Header auf jedem Endpoint.

Wie verifiziere ich, dass ein Webhook wirklich von CodeB stammt?

Der X-CodeB-Signature-Header ist HMAC-SHA256 des Roh-Request-Bodys mit dem Shared-Secret Ihrer Subscription. Berechnen Sie auf Ihrer Seite denselben HMAC und vergleichen Sie zeitkonstant, bevor Sie den Body parsen.

Was passiert mit meinem Sprach-Engine-API-Key?

Er wird für die Dauer des einen Anrufs verwendet, mit dem Sie ihn übergeben haben, und dann vergessen. Die Plattform speichert ihn nicht über den Anruf hinaus und schreibt ihn in keinen persistenten Log.

Wie steht es mit TCPA / DSGVO / ePrivacy-Compliance?

Die Plattform ist Transport: sie tätigt den Anruf, den Sie verlangen, und liefert einen auditierbaren Datensatz (CDR + optional Transkript + optional signierte Aufzeichnung). Einwilligung erfassen und Opt-outs respektieren liegt beim Anrufer.