Open in
Guida rapida (API)
Rispondi alla tua prima chiamata con un agente vocale IA: ottieni una chiave API, crea un agente, configura un numero di telefono ed effettua una chiamata di test dal vivo, tutto tramite l
Questa guida illustra le quattro chiamate REST necessarie per rispondere alla tua prima chiamata telefonica con un agente AI.
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 immediatamente nel tuo gestore dei segreti.
In questa guida, sostituisci sk_live_YOUR_API_KEY con il valore che hai
appena copiato. La chiave identifica automaticamente la tua organizzazione,
quindi non dovrai mai inserire un ID organizzazione negli URL.
Passaggio 2: Crea un agente
Un agente definisce come l'AI gestisce le conversazioni: prompt, voce, livello di prodotto, strumenti e idoneità del 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: Provisiona un numero di telefono
Questa chiamata richiede a ThunderPhone un numero e assegna il tuo nuovo agente come gestore delle chiamate in entrata. (Per portare il tuo numero da un provider VoIP, consulta invece 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 inizia 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 che ti servono.
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 questo segreto per verificare l'intestazione X-ThunderPhone-Signature-V2 nelle richieste in arrivo (vedi
Panoramica dei webhook).
Passaggio 5: Testa il tuo agente
Chiama il numero che hai appena provisionato. L'agente risponde, si presenta e segue il tuo prompt.
Esamina la chiamata al termine:
curl https://api.thunderphone.com/v1/calls \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"Esamina 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"