--- title: "Passer des appels sortants (API)" description: "Déclenchez un appel sortant piloté par l’IA depuis votre propre code — pour des flux d’enquête, de suivi ou de confirmation." --- 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’usage courants : - Confirmations de rendez-vous - Rappels d’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 tableau de bord (`/dashboard/campaigns`) accepte un CSV de contacts et gère pour vous les plages d’appel adaptées aux fuseaux horaires, la concurrence et la politique de relance. Ce guide couvre les appels programmatiques unitaires. ## Prérequis Utilisez un numéro que vous possédez via une [connexion VoIP](/api-reference/voip-connections), ou demandez l'autorisation d'utiliser vos numéros ThunderPhone pour les appels sortants depuis la page Phone Numbers. Les numéros ThunderPhone sont initialement réservés aux appels entrants. ThunderPhone examine chaque demande manuellement ; une fois approuvés, ces numéros peuvent passer des appels jusqu'à la limite quotidienne approuvée (réinitialisée à 00:00 UTC) et lancer des campagnes, et vous pouvez demander une limite plus élevée. Les numéros VoIP des clients n'ont pas de limite quotidienne ; nous les recommandons donc pour les appels sortants. 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 précise 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 compte ou activez le rechargement automatique dans **Organisation → Paramètres de facturation** du tableau de bord. Votre clé `sk_live_` peut vérifier le solde avec [`GET /v1/billing`](/api-reference/billing#get-billing-account), mais ne peut pas recharger le compte ni modifier le rechargement automatique. ## Passer un appel avec un agent enregistré La méthode la plus simple — référencer un agent par son identifiant : ```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 }' ``` Réponse : ```json { "call_id": 987654321, "status": "initiated" } ``` `status: "initiated"` signifie simplement que la requête a été acceptée — l’appel n’est **pas encore connecté**. Interrogez régulièrement [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call) pour connaître l’état en temps réel (`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, transmettez plutôt `config`. Sa structure correspond au schéma de réponse du [webhook `call.incoming`](/fr/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" } }' ``` ## Suivre l'appel En parallèle, abonnez-vous au [webhook `telephony.complete`](/fr/webhooks/events) — 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é. Si votre agent est configuré pour extraire des données structurées après l'appel, ces données sont livrées séparément une fois la finalisation terminée. ### Transmettre des variables par appel à un agent enregistré Les agents enregistrés peuvent utiliser des espaces réservés tels que `{{name}}` ou `{{name|there}}` dans le texte du prompt. Lorsque vous passez un appel sortant avec `agent_id`, transmettez `variables` avec les valeurs de cet appel : ```json { "from_number": "+[REDACTED_PHONE]", "to_number": "+[REDACTED_PHONE]", "agent_id": 12, "variables": { "name": "Jordan" } } ``` Utilisez des valeurs de chaîne associées au nom de l'espace réservé. Ces variables s'appliquent aux agents enregistrés ; l'exemple `config` en ligne de ce guide ne les utilise pas. ## Modes d'échec à gérer | Erreur | Correctif | |-------|-----| | `402 Payment Required` | Rechargez le solde ou activez le rechargement automatique | | `400` avec `code: destination_not_allowed` | ThunderPhone n'appelle pas ce numéro : numéros non valides, numéros d'urgence, numéros surtaxés, codes courts ou pays sous sanctions. Depuis des numéros ThunderPhone, seuls les numéros ordinaires des États-Unis et du Canada sont autorisés (sans numéros surtaxés). `reason` indique lequel ; consultez les [destinations bloquées](/api-reference/outbound-calls#blocked-destinations) | | `409` avec `retryable: false` pour un numéro ThunderPhone | Suivez le `code` : demandez l'autorisation d'appels sortants sur la page Numéros de téléphone, attendez l'examen en cours ou utilisez un autre numéro éligible | | `429` avec `code: platform_outbound_daily_limit_reached` | L'organisation a utilisé les appels sortants du jour depuis des numéros ThunderPhone. Attendez `resets_at` (00:00 UTC), demandez une limite plus élevée sur la page Numéros de téléphone ou appelez depuis un numéro sur votre propre connexion VoIP | | `429` avec `code: concurrent_call_limit_reached` | L'organisation a autant d'appels en cours que sa [limite d'appels simultanés](/api-reference/introduction#call-limits) (20 par défaut, en comptant les appels entrants, sortants, web et de test). Réessayez après le nombre de secondes indiqué par l'en-tête `Retry-After` ou lorsqu'un appel se termine ; envoyez un e-mail à support@thunderphone.com pour augmenter la limite | | `429` avec `code: same_number_too_soon` | Vous avez appelé le même `to_number` il y a moins de 10 secondes. Réessayez après le nombre de secondes indiqué par l'en-tête `Retry-After` | | `409` avec `retryable: false` pour un numéro VoIP client | Corrigez l'état indiqué par `code` ; en cas d'échec de vérification, exécutez [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) | | Conflit d'idempotence `409` | Réutilisez la clé uniquement avec la requête normalisée d'origine, ou envoyez une nouvelle clé | | `404 from_number is not registered to this organization` | Vérifiez que `from_number` correspond à un numéro de téléphone actif dans votre organisation. Un numéro déjà en cours de provisionnement, en échec, en cours de libération ou libéré renvoie également cette réponse | | `500` avec uniquement un champ `detail` | Aucun trunk sortant n'est configuré. Contactez le support ; il ne s'agit pas d'un problème d'état du numéro que vous pouvez corriger | | `502 Bad Gateway` | Échec SIP / LiveKit temporaire ; vous pouvez réessayer | Consultez la [référence des appels sortants](/api-reference/outbound-calls#error-responses) pour obtenir la liste complète et stable des codes d'éligibilité ainsi que les deux formats de réponse `409`. Si un numéro actif devient non éligible après l'acceptation de la requête mais avant le passage de l'appel, la vérification finale renvoie la charge utile `409` non réessayable. ## Contrôler le temps d'attente Les appels sortants qui durent longtemps parce que l'appelé répond lentement (arborescences IVR, files d'attente) peuvent être plafonnés avec `max_hold_seconds` : ```json { "from_number": "+15551234567", "to_number": "+14155552671", "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 secondes (15 minutes). --- ## Étapes suivantes Chaque champ de requête et code d'erreur. Transmettez les appels sortants terminés à votre système. Recharge automatique pour que les appels sortants n'échouent jamais faute de solde. Effectuez un test à blanc de votre agent sortant avant la production.