Démarrage rapide (API)

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

Vous aurez besoin d’un compte ThunderPhone. 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 permet d’atteindre ce même premier appel sans écrire de code.

Étape 1 : Obtenir une clé API

Se connecter

Ouvrez app.thunderphone.com.

Accéder à Clés

Dans le tableau de bord, accédez à Organisation → Clés.

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.

Vous êtes bloqué ? Créer une clé API serveur détaille cette procédure étape par étape, et le copilote intégré à l’application peut mettre en évidence chaque contrôle en direct.

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.

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"
  }'

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"])

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);

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 pour la comparaison complète.

É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.)

# 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}'

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"])

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.

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

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

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 :

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

Ajouter des outils de fonction

Permettez à votre agent d’appeler vos API pendant une conversation.

Passer des appels sortants

Déclenchez des appels depuis votre propre code.

Gérer les webhooks

Réagissez aux événements d’appel en temps réel.

Référence complète de l’API

Tous les endpoints publics, documentés.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Démarrage rapide (API)

Étape 1 : Obtenir une clé API

Étape 2 : Créer un agent

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

Étape 4 (facultative) : Configurer un webhook

Étape 5 : Tester votre agent

Étapes suivantes

Ajouter des outils de fonction

Passer des appels sortants

Gérer les webhooks

Référence complète de l’API

​Étape 1 : Obtenir une clé API

​Étape 2 : Créer un agent

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

​Étape 4 (facultative) : Configurer un webhook

​Étape 5 : Tester votre agent

​Étapes suivantes

Ajouter des outils de fonction

Passer des appels sortants

Gérer les webhooks

Référence complète de l’API

Étape 1 : Obtenir une clé API

Étape 2 : Créer un agent

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

Étape 4 (facultative) : Configurer un webhook

Étape 5 : Tester votre agent

Étapes suivantes