Passer des appels sortants (API)

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

Prérequis#

1. Choisir un numéro autorisé pour les appels sortants

   Utilisez un numéro que vous possédez via une connexion VoIP, 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.

2. Créer un agent

   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).

3. Maintenir un solde positif

   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, 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 :

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 :

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

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 :

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 — 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 :

{
  "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#

Consultez la référence des appels sortants 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 :

{
  "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#