> ## 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.
# Passer des appels sortants (API)
> Déclenchez un appel sortant piloté par l’IA depuis votre propre code — pour des enquêtes, des suivis ou des confirmations.
Les appels sortants vous permettent de fournir un numéro de destination et une
configuration d’agent à ThunderPhone afin que l’IA passe l’appel en votre
nom. Cas d’utilisation courants :
* Confirmations de rendez-vous
* Rappels pour des enquêtes
* Relances de « deuxième tentative » après un appel manqué
* Notifications de type répartition
Vous appelez toute une liste ? La fonctionnalité
[**Campagnes**](/fr/guides/outbound-campaigns) du dashboard
(`/dashboard/campaigns`) accepte un CSV de contacts et gère pour
vous les plages d’appel tenant compte des fuseaux horaires, la
concurrence et la stratégie de nouvelle tentative. Ce guide couvre
les appels programmatiques individuels.
## Prérequis
Les appels sortants nécessitent que vous possédiez le `from_number` via une
[connexion VoIP](/api-reference/voip-connections). Les numéros de démonstration
sont réservés aux appels entrants. Consultez
[Utiliser vos propres numéros](/fr/guides/bring-your-own-numbers).
Un prompt orienté appels sortants commence généralement par l’agent qui
s’identifie et explique son objectif — « Bonjour, Acme vous appelle pour
confirmer votre rendez-vous de demain à 15 h… » Définissez
`outbound_speak_order` sur `agent_first` (valeur par défaut).
Les appels sortants renvoient `402 Payment Required` si le solde est ≤
`$0.00`. Rechargez votre solde via
[`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
ou activez le [rechargement automatique](/api-reference/billing#update-auto-reload).
## Passer un appel avec un agent enregistré
La méthode la plus simple — référencer un agent par son identifiant :
```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
}'
```
Réponse :
```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` signifie uniquement que la requête a été acceptée — l’appel
n’est **pas encore connecté**. Interrogez
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
pour obtenir le statut en direct (`in_progress` → `completed` / `failed`).
## Passer un appel avec une configuration intégrée
Si vous souhaitez utiliser un prompt ponctuel qui ne mérite pas d’être enregistré comme agent,
passez plutôt `config`. Sa structure correspond au schéma de réponse du
[webhook `call.incoming`](/fr/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"
}
}'
```
## Suivre l’appel
En parallèle, abonnez-vous au
[webhook `telephony.complete`](/fr/webhooks/events) —
c’est le moyen le plus rapide de savoir qu’un appel est terminé. Si vous ne pouvez pas accepter les
webhooks entrants, interrogez `GET /v1/calls/{call_id}` toutes les quelques secondes ; l’enregistrement
inclut `end_reason`, `duration_seconds` et l’URL de l’enregistrement une fois l’appel terminé.
## Modes d’échec à gérer
| Erreur | Correctif |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required` | Rechargez le solde ou activez le rechargement automatique |
| `403` appels sortants bloqués (numéro de démonstration) | Utilisez plutôt un numéro VoIP |
| `403` appels sortants bloqués (VoIP non vérifiée) | Exécutez [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | Vérifiez que le `from_number` correspond à un numéro de téléphone que vous possédez |
| `502 Bad Gateway` | Échec SIP / LiveKit temporaire ; vous pouvez réessayer en toute sécurité |
## Contrôler le temps d'attente
Les appels sortants qui durent longtemps parce que la personne appelée répond lentement
(arborescences IVR, files d'attente) peuvent être plafonnés avec `max_hold_seconds` :
```json theme={null}
{
"from_number": "+15551234567",
"to_number": "+14155550199",
"agent_id": 12,
"max_hold_seconds": 120
}
```
L'agent raccroche si aucun audio humain n'a été reçu au cours des
N dernières secondes. La valeur par défaut est de 900 (15 minutes).
***
## Étapes suivantes
Chaque champ de requête et code d'erreur.
Transmettez les appels sortants terminés à votre système.
Recharge automatique afin que les appels sortants n'échouent jamais en raison du solde.
Exécutez un test à blanc de votre agent sortant avant la production.