--- title: "Ausgehende Anrufe tätigen (API)" description: "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 Möchten Sie eine ganze Liste anrufen? Die Funktion [**Kampagnen**](/de/guides/outbound-campaigns) 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 programmatische Anrufe. ## Voraussetzungen Verwenden Sie eine Nummer, die Sie über eine [VoIP-Verbindung](/api-reference/voip-connections) 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](/de/guides/bring-your-own-numbers). 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). 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`](/api-reference/billing#get-billing-account) 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: ```bash 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: ```json { "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}`](/api-reference/calls#retrieve-a-call) ab, um den Live-Status zu erhalten (`in_progress` → `completed` / `failed`). ## 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](/de/webhooks/call-incoming): ```bash 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](/de/webhooks/events) — 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: ```json { "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 | Fehler | Lösung | |-------|-----| | `402 Payment Required` | Laden Sie das Guthaben auf oder aktivieren Sie die automatische Aufladung | | `400` mit `code: destination_not_allowed` | ThunderPhone ruft diese Nummer nicht an: ungültige Nummern, Notrufnummern, Mehrwertnummern, Kurzwahlen oder sanktionierte Länder. Von ThunderPhone-Nummern aus sind nur reguläre US-amerikanische und kanadische Nummern zulässig (keine Mehrwertnummern). `reason` gibt an, welcher Grund zutrifft; siehe [gesperrte Ziele](/api-reference/outbound-calls#blocked-destinations) | | `409` mit `retryable: false` für eine ThunderPhone-Nummer | Folgen Sie dem `code`: Beantragen Sie ausgehende Anrufe auf der Seite Telefonnummern, warten Sie auf eine ausstehende Prüfung oder verwenden Sie eine andere berechtigte Nummer | | `429` mit `code: platform_outbound_daily_limit_reached` | Die Organisation hat ihr heutiges Kontingent für ausgehende Anrufe von ThunderPhone-Nummern ausgeschöpft. Warten Sie auf `resets_at` (00:00 UTC), beantragen Sie ein höheres Limit auf der Seite Telefonnummern oder rufen Sie von einer Nummer über Ihre eigene VoIP-Verbindung an | | `429` mit `code: concurrent_call_limit_reached` | Die Organisation hat so viele laufende Anrufe wie ihr [Limit für gleichzeitige Anrufe](/api-reference/introduction#call-limits) zulässt (standardmäßig 20, einschließlich eingehender, ausgehender, Web- und Testanrufe). Wiederholen Sie den Vorgang nach der im Header `Retry-After` angegebenen Anzahl Sekunden oder wenn ein Anruf endet; senden Sie eine E-Mail an support@thunderphone.com, um das Limit zu erhöhen | | `429` mit `code: same_number_too_soon` | Sie haben dieselbe `to_number` vor weniger als 10 Sekunden angerufen. Wiederholen Sie den Vorgang nach der im Header `Retry-After` angegebenen Anzahl Sekunden | | `409` mit `retryable: false` für eine Kunden-VoIP-Nummer | Korrigieren Sie den durch `code` angegebenen Status; führen Sie bei Überprüfungsfehlern [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) aus | | `409` Idempotenzkonflikt | Verwenden Sie den Schlüssel nur mit der ursprünglichen normalisierten Anfrage erneut oder senden Sie einen neuen Schlüssel | | `404 from_number is not registered to this organization` | Bestätigen Sie, dass `from_number` einer aktiven Telefonnummer in Ihrer Organisation entspricht. Eine Nummer, die bereits bereitgestellt wird, fehlgeschlagen ist, freigegeben wird oder freigegeben wurde, gibt ebenfalls diese Antwort zurück | | `500` mit nur einem `detail`-Feld | Es ist kein ausgehender Trunk konfiguriert. Wenden Sie sich an den Support; dies ist kein Problem mit dem Nummernstatus, das Sie beheben können | | `502 Bad Gateway` | Vorübergehender SIP-/LiveKit-Fehler; kann sicher wiederholt werden | Eine vollständige, stabile Liste der Berechtigungscodes und beide `409`-Antwortformate finden Sie in der [Referenz für ausgehende Anrufe](/api-reference/outbound-calls#error-responses). 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: ```json { "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 Jedes Anforderungsfeld und jeder Fehlercode. Übertragen Sie abgeschlossene ausgehende Anrufe an Ihr System. Automatische Aufladung, damit ausgehende Anrufe nicht aufgrund von Guthaben fehlschlagen. Führen Sie vor der Produktion einen Probelauf Ihres ausgehenden Agenten durch.