> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
Sie möchten 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 programmgesteuerte Anrufe.
## Voraussetzungen
Für ausgehende Anrufe müssen Sie die `from_number` über eine
[VoIP-Verbindung](/api-reference/voip-connections) besitzen. Demo-Nummern
sind nur für eingehende Anrufe verfügbar. Siehe
[Eigene Nummern mitbringen](/de/guides/bring-your-own-numbers).
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).
Ausgehende Anrufe geben `402 Payment Required` zurück, wenn das Guthaben ≤
`$0.00` beträgt. Laden Sie Guthaben über
[`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance) auf
oder aktivieren Sie [automatisches Aufladen](/api-reference/billing#update-auto-reload).
## Einen Anruf mit einem gespeicherten Agenten tätigen
Der einfachste Weg — einen Agenten über seine ID referenzieren:
```bash theme={null}
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:
```json theme={null}
{ "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)
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](/de/webhooks/call-incoming):
```bash theme={null}
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](/de/webhooks/events) —
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`](/api-reference/phone-numbers#verify-a-voip-sourced-number) 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:
```json theme={null}
{
"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
Jedes Anfragefeld und jeder Fehlercode.
Übertragen Sie abgeschlossene ausgehende Anrufe an Ihr System.
Automatisches Aufladen, damit ausgehende Anrufe nie am Guthaben scheitern.
Testen Sie Ihren ausgehenden Agenten vor dem Produktionseinsatz.