> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  Vous créez votre premier agent à la main ? Le dashboard vous guide dans ce flux précis — créer l’agent, ajouter un numéro, simuler, vérifier — grâce à un assistant guidé. Commencez par le
  [guide de démarrage rapide du dashboard](/fr/quickstart-dashboard).
</Note>

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](/api-reference/agents) pour tous les champs de configuration ; le minimum requis est :

```bash theme={null}
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.

<Tip>
  Choisissez `spark` pour des questions-réponses simples au coût le plus bas, et `bolt` lorsque la rapidité est primordiale. 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).
</Tip>

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

```bash theme={null}
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}`](/api-reference/phone-numbers#retrieve-a-phone-number)
pour suivre la transition si nécessaire.

<Note>
  Pour la production, ignorez les numéros de démonstration et
  [apportez vos propres numéros via VoIP](/fr/guides/bring-your-own-numbers).
  Les numéros de démonstration sont réservés aux appels entrants et leur volume est limité.
</Note>

## 3. Attribuer l’agent

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

```bash theme={null}
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`](/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.

## 5. Examiner les résultats

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

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Récupérez la transcription :

```bash theme={null}
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) :

```bash theme={null}
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`](/fr/webhooks/events),
vous recevrez les mêmes données sous forme de POST vers votre serveur ; consultez
[call.complete](/fr/webhooks/call-complete).

***

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Configuration dynamique par appel" icon="bolt" href="/fr/guides/dynamic-call-config">
    Sélectionnez un agent différent pour chaque appelant selon le numéro de téléphone ou
    une logique personnalisée dans un webhook.
  </Card>

  <Card title="Ajouter des intégrations d’outils" icon="screwdriver-wrench" href="/fr/guides/build-tool-integration">
    Permettez à l’agent d’appeler vos API au cours de la conversation.
  </Card>

  <Card title="Recevoir des webhooks call.complete" icon="bolt" href="/fr/webhooks/call-complete">
    Transmettez chaque appel terminé à votre pipeline CRM / analytique.
  </Card>

  <Card title="Évaluation par IA et rapports de problèmes" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Évaluez automatiquement chaque appel et acheminez ceux signalés pour révision.
  </Card>
</CardGroup>