Developer cookbook

Ausgehende Anrufe tätigen (API)

Starten Sie aus Ihrem eigenen Code einen KI-gesteuerten ausgehenden Anruf — für Umfragen, Nachfassaktionen oder Bestätigungsabläufe.

Mit ausgehenden Anrufen können Sie ThunderPhone eine Zielnummer und eine Agentenkonfiguration übergeben, damit die Sprach-KI den Anruf in Ihrem Namen tätigt. Typische Anwendungsfälle:

• Terminbestätigungen
• Rückrufe für Umfragen
• „Zweiter Versuch“-Follow-ups nach einem verpassten Anruf
• Benachrichtigungen im Stil einer Einsatzdisposition

Voraussetzungen#

1. Eine VoIP-Nummer bereitstellen

   Für ausgehende Anrufe müssen Sie die from_number über eine VoIP-Verbindung besitzen. Demo-Nummern sind nur für eingehende Anrufe verfügbar. Siehe Eigene Nummern mitbringen.

2. Einen Agenten erstellen

   Ein auf ausgehende Anrufe ausgerichteter Prompt beginnt in der Regel damit, dass sich der Agent und sein Zweck vorstellt — „Guten Tag, hier ist Acme. Ich rufe an, um Ihren Termin morgen um 15 Uhr zu bestätigen …“ Setzen Sie outbound_speak_order auf agent_first (die Standardeinstellung).

3. Ein ausreichendes Guthaben sicherstellen

   Ausgehende Anrufe geben 402 Payment Required zurück, wenn das Guthaben ≤ $0.00 beträgt. Laden Sie Guthaben über POST /v1/billing/top-up auf oder aktivieren Sie automatisches Aufladen.

Einen Anruf mit einem gespeicherten Agenten tätigen#

Der einfachste Weg — einen Agenten über seine ID referenzieren:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'

Antwort:

{ "call_id": 987654321, "status": "initiated" }

Einen Anruf mit Inline-Konfiguration tätigen#

Wenn Sie einen einmaligen Prompt verwenden möchten, den Sie nicht als Agenten speichern möchten, übergeben Sie stattdessen config. Die Struktur entspricht dem Antwortschema des call.incoming-Webhooks:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Den Anruf verfolgen#

Abonnieren Sie parallel den telephony.complete-Webhook — dies ist der schnellste Weg, um zu erfahren, dass ein Anruf beendet wurde. Wenn Sie keine eingehenden Webhooks empfangen können, fragen Sie GET /v1/calls/{call_id} alle paar Sekunden ab; der Datensatz enthält nach Ende des Anrufs end_reason, duration_seconds und die URL der Aufzeichnung.

Fehlerfälle, die Sie behandeln sollten#

Steuerung der Wartezeit#

Ausgehende Anrufe, die lange dauern, weil der Angerufene nur langsam reagiert (IVR-Menüs, Warteschlangen), können mit max_hold_seconds begrenzt werden:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

Der Agent legt auf, wenn in den letzten N Sekunden kein menschliches Audio empfangen wurde. Der Standardwert ist 900 (15 Minuten).

Nächste Schritte#