Developer cookbook

Eingehende Anrufe verarbeiten (API)

End-to-End: Konfigurieren Sie einen Agenten, weisen Sie ihn einer Telefonnummer zu, nehmen Sie einen Anruf entgegen und prüfen Sie das Transkript.

Der Standardablauf zum „Beantworten eines Telefons mit KI“ direkt aus Ihrem Terminal. Sie werden:

1. Einen Agenten mit Prompt und Stimme erstellen.
2. Eine Telefonnummer bereitstellen (oder mitbringen) und den Agenten als Handler für eingehende Anrufe zuweisen.
3. Die Nummer anrufen. Anrufprotokoll, Transkript und Aufzeichnung prüfen.

API-Aufrufe insgesamt: vier. Gesamtzeit: unter fünf Minuten.

1. Einen Agenten erstellen#

Ein Agent bündelt Prompt, Stimme und Produkttarif, die den Anruf steuern. Eine Übersicht aller Konfigurationsfelder finden Sie unter Agenten; das Minimum ist:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Speichern Sie die zurückgegebene id — Sie benötigen sie in Schritt 2.

2. Eine Telefonnummer erhalten#

Wenn Sie nur eine Nummer zum Anrufen benötigen, stellen Sie eine Demo-Nummer aus dem ThunderPhone-Pool bereit:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

Die Antwort enthält eine id und eine number im E.164-Format. Demo-Nummern starten mit status="provisioning" und werden innerhalb weniger Sekunden active — fragen Sie GET /v1/phone-numbers/{id} ab, um den Übergang zu verfolgen, falls Sie ihn benötigen.

3. Den Agenten zuweisen#

Verknüpfen Sie den Agenten aus Schritt 1 mit der Richtung für eingehende Anrufe der Nummer:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Das ist alles — die Nummer ist aktiv. Sie können im selben PATCH auch outbound_agent_id festlegen, damit die Nummer ebenfalls für ausgehende Anrufe bereit ist.

4. Einen Anruf entgegennehmen#

Wählen Sie die Nummer von Ihrem Telefon aus. Der Agent nimmt ab, stellt sich gemäß Ihrem Prompt vor, und das Gespräch beginnt.

Während der Anruf läuft, erscheint er in GET /v1/calls mit status="in_progress". Nach dem Ende wird der Datensatz mit end_reason, duration_seconds, billable_minutes und (später) einer Aufzeichnungs-URL sowie einer KI-Bewertung aktualisiert.

5. Die Ergebnisse prüfen#

Rufen Sie die Liste der letzten Anrufe ab:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Rufen Sie das Transkript ab:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Und die Aufzeichnungs-URL (kurzlebig, signiert):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Wenn Sie den Webhook telephony.complete abonniert haben, erhalten Sie dieselben Daten als POST an Ihren Server — siehe call.complete.

Nächste Schritte#