Developer cookbook

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

Prérequis#

1. Fournir un numéro VoIP

   Les appels sortants nécessitent que vous possédiez le from_number via une connexion VoIP. Les numéros de démonstration sont réservés aux appels entrants. 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 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).

3. Conserver un solde positif

   Les appels sortants renvoient 402 Payment Required si le solde est ≤ $0.00. Rechargez votre solde via POST /v1/billing/top-up ou activez 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":   "+14155550199",
    "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, passez 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":   "+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 — 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#

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 :

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