Ausgehende Anrufe tätigen (API)

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

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

• Terminbestätigungen
• Rückrufe für Umfragen
• „Zweiter Versuch“-Nachfassaktionen nach einem verpassten Anruf
• Benachrichtigungen im Dispatch-Stil

Voraussetzungen#

1. Eine für ausgehende Anrufe aktivierte Nummer auswählen

   Verwenden Sie eine Nummer, die Sie über eine VoIP-Verbindung besitzen, oder beantragen Sie auf der Seite „Telefonnummern“ die Berechtigung, Ihre ThunderPhone-Nummern für ausgehende Anrufe zu verwenden. ThunderPhone-Nummern sind zunächst nur für eingehende Anrufe verfügbar. ThunderPhone prüft jeden Antrag manuell; nach der Genehmigung können diese Nummern Anrufe bis zum genehmigten Tageslimit tätigen (wird um 00:00 UTC zurückgesetzt) und Kampagnen ausführen. Sie können auch ein höheres Limit beantragen. VoIP-Nummern von Kunden haben kein Tageslimit, daher empfehlen wir sie für ausgehende Anrufe. Siehe Eigene Nummern verwenden.

2. Einen Agenten erstellen

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

3. Ein positives Guthaben beibehalten

   Ausgehende Anrufe geben 402 Payment Required zurück, wenn das Guthaben ≤ $0.00 ist. Laden Sie Guthaben auf oder aktivieren Sie das automatische Aufladen unter Organisation → Abrechnungseinstellungen im Dashboard. Ihr sk_live_- Schlüssel kann das Guthaben mit GET /v1/billing prüfen, kann jedoch kein Guthaben aufladen oder das automatische Aufladen ändern.

Tätigen Sie einen Anruf mit einem gespeicherten Agenten#

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

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":   "+14155552671",
    "agent_id":    12
  }'

Antwort:

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

Tätigen Sie einen Anruf mit Inline-Konfiguration#

Wenn Sie einen einmaligen Prompt verwenden möchten, der es nicht wert ist, als Agent gespeichert zu werden, ü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":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Anruf verfolgen#

Abonnieren Sie parallel den telephony.complete-Webhook — 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 Aufzeichnungs-URL.

Wenn Ihr Agent so eingerichtet ist, dass er nach dem Anruf strukturierte Daten extrahiert, werden diese Daten nach Abschluss der Finalisierung separat bereitgestellt.

Variablen pro Anruf an einen gespeicherten Agenten übergeben#

Gespeicherte Agenten können Platzhalter wie {{name}} oder {{name|there}} im Prompt-Text verwenden. Wenn Sie einen ausgehenden Anruf mit agent_id tätigen, übergeben Sie variables mit den Werten für diesen Anruf:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Verwenden Sie Zeichenfolgenwerte mit dem Platzhalternamen als Schlüssel. Diese Variablen gelten für gespeicherte Agenten; das Inline-Beispiel config in diesem Leitfaden verwendet sie nicht.

Zu behandelnde Fehlermodi#

Eine vollständige, stabile Liste der Berechtigungscodes und beide 409-Antwortformate finden Sie in der Referenz für ausgehende Anrufe. Wenn eine aktive Nummer nach Annahme der Anfrage, aber vor dem Tätigen des Anrufs nicht mehr berechtigt ist, gibt die abschließende Prüfung die nicht wiederholbare 409-Nutzlast zurück.

Wartezeit steuern#

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

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

Der Agent legt auf, wenn in den letzten N Sekunden keine menschliche Stimme empfangen wurde. Der Standardwert beträgt 900 Sekunden (15 Minuten).

Nächste Schritte#