Ausgehende Anrufe tätigen (API)

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

Sie möchten eine ganze Liste anrufen? Die Funktion Kampagnen im Dashboard (/dashboard/campaigns) verarbeitet eine CSV-Datei mit Kontakten und übernimmt zeitzonenabhängige Anruffenster, Parallelität und Wiederholungsrichtlinien für Sie. Dieser Leitfaden behandelt einzelne programmgesteuerte Anrufe.

Voraussetzungen

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.

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).

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" }

status: "initiated" bedeutet lediglich, dass die Anfrage akzeptiert wurde — der Anruf ist noch nicht verbunden. Fragen Sie GET /v1/calls/{call_id} nach dem Live-Status ab (in_progress → completed / failed).

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

Fehler	Lösung
`402 Payment Required`	Guthaben aufladen oder automatisches Aufladen aktivieren
`403` ausgehend blockiert (Demo-Nummer)	Stattdessen eine VoIP-Nummer bereitstellen
`403` ausgehend blockiert (nicht verifizierte VoIP-Nummer)	`POST /v1/phone-numbers/{id}/verify-voip` ausführen
`404 from_number is not registered to this organization`	Bestätigen Sie, dass `from_number` mit einer Telefonnummer übereinstimmt, die Ihnen gehört
`502 Bad Gateway`	Vorübergehender SIP-/LiveKit-Fehler; Wiederholung ist sicher

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

Referenz für ausgehende Anrufe

Jedes Anfragefeld und jeder Fehlercode.

call.complete empfangen

Übertragen Sie abgeschlossene ausgehende Anrufe an Ihr System.

Abrechnung

Automatisches Aufladen, damit ausgehende Anrufe nie am Guthaben scheitern.

Ausgehende Agenten testen

Testen Sie Ihren ausgehenden Agenten vor dem Produktionseinsatz.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Ausgehende Anrufe tätigen (API)

Voraussetzungen

Einen Anruf mit einem gespeicherten Agenten tätigen

Einen Anruf mit Inline-Konfiguration tätigen

Den Anruf verfolgen

Fehlerfälle, die Sie behandeln sollten

Steuerung der Wartezeit

Nächste Schritte

Referenz für ausgehende Anrufe

call.complete empfangen

Abrechnung

Ausgehende Agenten testen

​Voraussetzungen

​Einen Anruf mit einem gespeicherten Agenten tätigen

​Einen Anruf mit Inline-Konfiguration tätigen

​Den Anruf verfolgen

​Fehlerfälle, die Sie behandeln sollten

​Steuerung der Wartezeit

​Nächste Schritte

Referenz für ausgehende Anrufe

call.complete empfangen

Abrechnung

Ausgehende Agenten testen

Voraussetzungen

Einen Anruf mit einem gespeicherten Agenten tätigen

Einen Anruf mit Inline-Konfiguration tätigen

Den Anruf verfolgen

Fehlerfälle, die Sie behandeln sollten

Steuerung der Wartezeit

Nächste Schritte