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

Getting Started

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, attribuez un numéro de téléphone et passez un appel de test en direct — le tout via l’API 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.

Étape 1 : Obtenir une clé API

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

    Accédez à Organisation → Clés dans le dashboard.

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

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 dans les 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 compatibilité avec les widgets.

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 au pool de démo de 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 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 point de terminaison 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 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"

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

Chaque point de terminaison public, documenté.