Gérer les appels entrants (API)

De bout en bout : configurez un agent, attribuez-le à un numéro de téléphone, prenez un appel et consultez la transcription.

Le flux canonique « répondre au téléphone avec une IA », depuis votre terminal. Vous allez :

1. Créer un agent avec un prompt et une voix.
2. Provisionner (ou apporter) un numéro de téléphone et attribuer l’agent comme gestionnaire des appels entrants.
3. Appeler le numéro. Consulter le journal d’appels, la transcription et l’enregistrement.

Nombre total d’appels API : quatre. Durée totale : moins de cinq minutes.

1. Créer un agent#

Un agent regroupe le prompt, la voix et le niveau de produit qui piloteront l'appel. Vous pouvez également définir des limites d'appel telles que max_call_duration_seconds et ring_duration_seconds sur l'agent. Les agents prennent aussi en charge intro_clip et intro_ring_count pour diffuser une introduction préenregistrée et jusqu'à deux sonneries avant que l'agent ne parle. Les nouveaux agents nécessitent également un fuseau horaire. Si votre agent est multilingue, vous pouvez définir language_switching pour contrôler s'il demande avant de changer de langue ou s'il suit la langue de l'appelant. Consultez Agents pour tous les champs de configuration ; le minimum est :

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Enregistrez l’id renvoyé — vous en aurez besoin à l’étape 2.

2. Obtenir un numéro de téléphone#

Si vous avez simplement besoin d’un numéro à appeler, obtenez un numéro ThunderPhone depuis le pool de ThunderPhone :

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

La réponse inclut un id et un number au format E.164. Les numéros ThunderPhone commencent avec le status="provisioning" et deviennent active en quelques secondes — interrogez régulièrement GET /v1/phone-numbers/{id} pour suivre la transition si nécessaire.

3. Attribuer l’agent#

Associez l’agent de l’étape 1 à la direction entrante du numéro :

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

C’est tout — le numéro est actif. Une fois les appels sortants approuvés pour votre organisation, vous pouvez également définir outbound_agent_id dans le même PATCH. D’ici là, l’API rejette cette attribution avec 400.

Si vous acheminez les appels entrants via un webhook de configuration plutôt qu’un inbound_agent_id fixe, ce webhook peut désormais renvoyer un timezone par appel, ainsi que agent_id et variables.

4. Prendre un appel#

Appelez le numéro depuis votre téléphone. L’agent répond, se présente conformément à votre prompt, puis la conversation commence.

Pendant que l’appel est en cours, il apparaît dans GET /v1/calls avec status="in_progress". Lorsqu’il se termine, l’enregistrement est mis à jour avec end_reason, duration_seconds, billable_minutes et, à terme, une URL d’enregistrement et une évaluation par IA.

Les appels entrants sont pris en compte dans la limite d’appels simultanés de votre organisation (20 appels en cours par défaut, partagés avec les appels sortants, web et de test). Tout appel arrivant à cette limite est refusé avant que l’agent ne réponde et est raccroché, n’est pas facturé et est enregistré comme un appel échoué avec le motif de fin concurrent_call_limit_reached. Envoyez un e-mail à support@thunderphone.com si vous avez besoin d’une limite plus élevée.

5. Inspecter les résultats#

Récupérez la liste des appels récents :

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Récupérez la transcription :

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Et l’URL de l’enregistrement (signée, à durée de validité limitée) :

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Si vous êtes abonné au webhook telephony.complete, vous recevrez les mêmes données sous la forme d’une requête POST vers votre serveur. Consultez call.complete.

Si des champs d’extraction sont configurés pour votre agent, la charge utile de l’appel terminé peut également inclure des données extraites structurées.

Étapes suivantes#