---
title: "Gérer les appels entrants (API)"
description: "De bout en bout : configurez un agent, attribuez-le à un numéro de téléphone, prenez un appel et consultez la transcription."
---
Vous créez votre premier agent manuellement ? Le dashboard vous guide dans ce
flux exact — créer l’agent, ajouter un numéro, simuler, vérifier — avec un
assistant guidé. Commencez par le
[guide de démarrage rapide du dashboard](/fr/quickstart-dashboard).
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](/api-reference/agents) pour tous les champs de configuration ; le
minimum est :
```bash
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.
Choisissez `spark` pour des questions-réponses simples au coût le plus bas, et `bolt` lorsque la vitesse
est prioritaire. Passez à `storm-base-with-ack` lorsque votre prompt
nécessite un raisonnement plus approfondi et peut tolérer un acquiescement verbal d’une demi-seconde pendant que
le modèle réfléchit. Consultez les
[niveaux de produit](/api-reference/agents#product-tiers-at-a-glance).
## 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 :
```bash
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}`](/api-reference/phone-numbers#retrieve-a-phone-number)
pour suivre la transition si nécessaire.
Les numéros ThunderPhone sont initialement réservés aux appels entrants. Un administrateur de l’organisation peut demander
l’activation des appels sortants depuis la page Numéros de téléphone. ThunderPhone examine chaque
demande manuellement ; une fois approuvés, les numéros peuvent passer des appels et exécuter
des campagnes. Les numéros VoIP des clients ne changent pas.
## 3. Attribuer l’agent
Associez l’agent de l’étape 1 à la direction entrante du numéro :
```bash
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`](/api-reference/calls#list-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](/api-reference/introduction#call-limits) 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 :
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Récupérez la transcription :
```bash
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) :
```bash
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`](/fr/webhooks/events),
vous recevrez les mêmes données sous la forme d’une requête POST vers votre serveur. Consultez
[call.complete](/fr/webhooks/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
Sélectionnez un agent différent pour chaque appelant selon son numéro de téléphone ou
une logique personnalisée dans un webhook.
Permettez à l’agent d’appeler vos API en cours de conversation.
Acheminez directement les appelants ou filtrez le destinataire avant de les mettre en relation.
Envoyez chaque appel terminé vers votre pipeline CRM / analytique.
Évaluez automatiquement chaque appel et acheminez ceux qui sont signalés pour révision.