Guida rapida (API)
Rispondi alla tua prima chiamata telefonica con un agente vocale AI: ottieni una chiave API, crea un agente, assegna un numero di telefono ed effettua una chiamata di prova in tempo reale, tutto tramite l
Questa guida illustra le quattro chiamate REST necessarie per rispondere alla tua prima telefonata con un agente IA.
Passaggio 1: Ottieni una chiave API
- Accedi
Apri app.thunderphone.com.
- Vai a Chiavi
Nella dashboard, vai a Organizzazione → Chiavi.
- Crea una chiave
Fai clic su Crea chiave, assegnale un nome e copia il valore
sk_live_.... La chiave non elaborata viene mostrata una sola volta: salvala subito nel tuo gestore di segreti.
In tutta questa guida, sostituisci sk_live_YOUR_API_KEY con il valore che hai
appena copiato. La chiave identifica automaticamente la tua organizzazione, quindi
non devi mai inserire un ID organizzazione negli URL.
Passaggio 2: Crea un agente
Un agente definisce il modo in cui l'IA gestisce le conversazioni: prompt, voce, livello di prodotto, strumenti e idoneità per i 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);Passaggio 3: Effettua il provisioning di un numero di telefono
Questa chiamata richiede un numero al pool demo di ThunderPhone e assegna il tuo nuovo agente come gestore delle chiamate in entrata. (Per portare il tuo numero da un provider VoIP, consulta invece le connessioni 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"])Il tuo nuovo numero parte con status="provisioning" e passa a
active entro pochi secondi; quando chiudi il browser, il
numero è pronto a ricevere chiamate.
Passaggio 4 (facoltativo): Configura un webhook
Per gli eventi in tempo reale (instradamento dinamico delle chiamate, elaborazione post-chiamata) aggiungi un endpoint webhook. Iscriviti solo agli eventi di cui hai bisogno.
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 risposta contiene un secret monouso: copialo nel tuo gestore
di segreti. Usa quel segreto per verificare l'header
X-ThunderPhone-Signature nelle richieste in arrivo (consulta la
panoramica dei webhook).
Passaggio 5: Testa il tuo agente
Chiama il numero di cui hai appena effettuato il provisioning. L'agente risponde, si presenta e segue il tuo prompt.
Esamina la chiamata dopo la sua conclusione:
curl https://api.thunderphone.com/v1/calls \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Analizza una chiamata specifica per recuperare la trascrizione e l'URL della registrazione:
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"