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

# Démarrage rapide (API)

> Répondez à votre premier appel téléphonique avec un agent IA en quatre appels REST.

Ce guide vous présente les quatre appels REST nécessaires pour répondre
à votre premier appel téléphonique avec un agent IA.

<Info>
  Vous aurez besoin d’un [compte ThunderPhone](https://app.thunderphone.com).
  L’inscription est gratuite et prend moins d’une minute. Vous préférez cliquer plutôt qu’utiliser curl ?
  Le [quickstart du tableau de bord](/fr/quickstart-dashboard) permet d’atteindre ce même
  premier appel sans écrire de code.
</Info>

## Étape 1 : Obtenir une clé API

<Steps>
  <Step title="Se connecter">
    Ouvrez [app.thunderphone.com](https://app.thunderphone.com).
  </Step>

  <Step title="Accéder à Clés">
    Dans le tableau de bord, accédez à **Organisation → Clés**.
  </Step>

  <Step title="Créer une clé">
    Cliquez sur **Créer une clé**, donnez-lui un nom et copiez la valeur
    `sk_live_...`. La clé brute n’est affichée **qu’une seule fois** : enregistrez-la
    immédiatement dans votre gestionnaire de secrets.
  </Step>
</Steps>

<Tip>
  Vous êtes bloqué ? [Créer une clé API serveur](/fr/guides/api-keys) détaille
  cette procédure étape par étape, et le copilote intégré à l’application peut
  mettre en évidence chaque contrôle en direct.
</Tip>

Dans ce guide, remplacez `sk_live_YOUR_API_KEY` par la valeur que vous
venez de copier. La clé identifie automatiquement votre organisation ; vous
n’avez donc jamais besoin d’ajouter un identifiant d’organisation aux URL.

## Étape 2 : Créer un agent

Un agent définit la manière dont l’IA gère les conversations : prompt, voix,
niveau de produit, outils et éligibilité au widget.

<CodeGroup>
  ```bash cURL 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":   "Customer Support",
      "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
      "voice":  "john",
      "product": "spark"
    }'
  ```

  ```python Python theme={null}
  import os, requests

  agent = requests.post(
      "https://api.thunderphone.com/v1/agents",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={
          "name":   "Customer Support",
          "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
          "voice":  "john",
          "product": "spark",
      },
  ).json()
  print("Agent id:", agent["id"])
  ```

  ```javascript Node.js theme={null}
  const agent = await fetch("https://api.thunderphone.com/v1/agents", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name:    "Customer Support",
      prompt:  "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
      voice:   "john",
      product: "spark",
    }),
  }).then((r) => r.json());
  console.log("Agent id:", agent.id);
  ```
</CodeGroup>

<Tip>
  Niveaux de produit : `spark` est optimisé pour le coût, `bolt` pour la vitesse et
  `storm-base` / `storm-extra` pour l’intelligence sur les prompts complexes. Consultez
  [Agents](/api-reference/agents#product-tiers-at-a-glance) pour la comparaison
  complète.
</Tip>

## Étape 3 : Provisionner un numéro de téléphone

Cet appel demande un numéro au pool de démonstration de ThunderPhone et attribue votre
nouvel agent comme gestionnaire des appels entrants. (Pour utiliser votre propre numéro provenant d’un fournisseur
VoIP, consultez plutôt les [connexions VoIP](/api-reference/voip-connections).)

<CodeGroup>
  ```bash cURL theme={null}
  # First provision
  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"}'

  # Then assign the agent you created in Step 2
  curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/<id-from-previous> \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"inbound_agent_id": 12}'
  ```

  ```python Python theme={null}
  number = requests.post(
      "https://api.thunderphone.com/v1/phone-numbers",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={"area_code": "415"},
  ).json()
  requests.patch(
      f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={"inbound_agent_id": agent["id"]},
  )
  print("Your ThunderPhone number:", number["number"])
  ```
</CodeGroup>

Votre nouveau numéro démarre avec le statut `status="provisioning"` et passe à
`active` en quelques secondes ; lorsque vous fermez votre navigateur, le
numéro est prêt à recevoir des appels.

## Étape 4 (facultative) : Configurer un webhook

Pour les événements en temps réel (routage dynamique des appels, traitement après appel), ajoutez
un endpoint webhook. Abonnez-vous uniquement aux événements dont vous avez besoin.

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod webhook",
    "url":    "https://your-server.com/thunderphone-webhook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'
```

La réponse contient un `secret` à usage unique — copiez-le dans votre gestionnaire
de secrets. Utilisez ce secret pour vérifier l’en-tête
`X-ThunderPhone-Signature` des requêtes entrantes (consultez la
[présentation des webhooks](/fr/webhooks/overview)).

## Étape 5 : Tester votre agent

Appelez le numéro que vous venez de provisionner. L’agent décroche, se présente
et suit votre prompt.

Examinez l’appel après sa fin :

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

Accédez à un appel spécifique pour récupérer la transcription et l’URL de l’enregistrement :

```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

***

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Ajouter des outils de fonction" icon="screwdriver-wrench" href="/fr/tools/overview">
    Permettez à votre agent d’appeler vos API pendant une conversation.
  </Card>

  <Card title="Passer des appels sortants" icon="arrow-up-right" href="/api-reference/outbound-calls">
    Déclenchez des appels depuis votre propre code.
  </Card>

  <Card title="Gérer les webhooks" icon="bolt" href="/fr/webhooks/overview">
    Réagissez aux événements d’appel en temps réel.
  </Card>

  <Card title="Référence complète de l’API" icon="book" href="/api-reference/introduction">
    Tous les endpoints publics, documentés.
  </Card>
</CardGroup>