ThunderPhone 2.0 est disponible.En libre-service, à partir de 2 ¢/min.Découvrir l’annonce
Commencer

Getting Started

View as Markdown
Open in
ClaudeChatGPTCursor

Démarrage rapide (API)

Répondez à votre premier appel téléphonique avec un agent vocal IA : obtenez une clé API, créez un agent, provisionnez un numéro de téléphone et passez un appel de test en direct — le tout via l’API REST.

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

Étape 1 : Obtenir une clé API

  1. Se connecter
  2. Accéder aux clés

    Dans le dashboard, accédez à Organisation → Clés.

  3. Créer une clé

    Cliquez sur Créer une clé, donnez-lui un nom, puis 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.

Tout au long de 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
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
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"])
Node.js
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);

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

Cet appel demande un numéro à ThunderPhone et attribue votre nouvel agent comme gestionnaire des appels entrants. (Pour utiliser votre propre numéro depuis un fournisseur VoIP, consultez plutôt les connexions VoIP.)

cURL
# 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
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 status="provisioning" et passe à active en quelques secondes ; lorsque vous raccrochez dans 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-V2 sur les requêtes entrantes (voir Présentation des webhooks).

Étape 5 : Tester votre agent

Appelez le numéro que vous venez de provisionner. L'agent répond, se présente et suit votre prompt.

Examinez l'appel une fois terminé :

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

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