---
title: "Guida rapida (API)"
description: "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'API REST."
---
Questa guida illustra le quattro chiamate REST necessarie per rispondere
alla tua prima chiamata telefonica con un agente AI.
Ti servirà un [account ThunderPhone](https://app.thunderphone.com).
La registrazione è gratuita e richiede meno di un minuto. Preferisci fare clic invece di usare curl?
Il [quickstart della dashboard](/it/quickstart-dashboard) ti porta alla stessa
prima chiamata senza scrivere codice.
## Passaggio 1: Ottieni una chiave API
Apri [app.thunderphone.com](https://app.thunderphone.com).
Nella dashboard, vai a **Organizzazione → Chiavi**.
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.
Bloccato? [Crea una chiave API del server](/it/guides/api-keys) illustra
questo flusso passo dopo passo, mentre il copilota nell'app può
evidenziare ogni controllo in tempo reale.
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.
```bash 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 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"])
```
```javascript 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);
```
Livelli di prodotto: `spark` è ottimizzato per i costi, `bolt` per la velocità e
`storm-base` / `storm-extra` per l'intelligenza su prompt complessi. Consulta
[Agenti](/api-reference/agents#product-tiers-at-a-glance) per il confronto
completo.
## 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](/api-reference/voip-connections).)
```bash 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/ \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inbound_agent_id": 12}'
```
```python 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"])
```
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.
```bash
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](/it/webhooks/overview)).
## 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:
```bash
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:
```bash
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"
```
---
## Passaggi successivi
Consenti al tuo agente di chiamare le tue API durante una conversazione.
Avvia chiamate dal tuo codice.
Reagisci agli eventi delle chiamate in tempo reale.
Ogni endpoint pubblico, documentato.