Developer cookbook

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 pour « 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. Observez le journal d’appels, la transcription et l’enregistrement.

Nombre total d’appels API : quatre. Temps total : 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. Consultez Agents pour tous les champs de configuration ; le minimum requis 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, provisionnez un numéro de démonstration 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 de démonstration commencent avec le status="provisioning" et deviennent active en quelques secondes : interrogez 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. Vous pouvez également définir outbound_agent_id dans le même PATCH afin que le numéro soit aussi prêt à émettre des appels.

4. Prendre un appel#

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

Pendant l’appel, 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.

5. Examiner 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 d’enregistrement (signée et de courte durée) :

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

Si vous vous êtes abonné au webhook telephony.complete, vous recevrez les mêmes données sous forme de POST vers votre serveur ; consultez call.complete.

Étapes suivantes#