Guida rapida (API)

Questa guida illustra le quattro chiamate REST necessarie per rispondere alla tua prima chiamata telefonica con un agente AI.

Ti serve un account ThunderPhone. La registrazione è gratuita e richiede meno di un minuto. Preferisci fare clic anziché usare curl? La guida rapida della dashboard porta alla stessa prima chiamata senza scrivere codice.

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.

Bloccato? Crea una chiave API del server illustra questo flusso passo per passo e il copilota integrato può evidenziare ogni controllo per te 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 devi 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à per il 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);

Livelli di prodotto: spark è ottimizzato per i costi, bolt per la velocità e storm-base / storm-extra per l’intelligenza con prompt complessi. Consulta Agenti per il confronto completo.

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 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 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 dei segreti. Usa tale segreto per verificare l’header X-ThunderPhone-Signature nelle richieste in entrata (consulta 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"

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"

Passaggi successivi

Aggiungi strumenti funzione

Consenti al tuo agente di chiamare le tue API durante una conversazione.

Effettua chiamate in uscita

Avvia chiamate dal tuo codice.

Gestisci i webhook

Reagisci agli eventi delle chiamate in tempo reale.

Riferimento API completo

Ogni endpoint pubblico, documentato.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Passaggio 1: Ottieni una chiave API

Passaggio 2: Crea un agente

Passaggio 3: Effettua il provisioning di un numero di telefono

Passaggio 4 (facoltativo): Configura un webhook

Passaggio 5: Testa il tuo agente

Passaggi successivi

Aggiungi strumenti funzione

Effettua chiamate in uscita

Gestisci i webhook

Riferimento API completo

​Passaggio 1: Ottieni una chiave API

​Passaggio 2: Crea un agente

​Passaggio 3: Effettua il provisioning di un numero di telefono

​Passaggio 4 (facoltativo): Configura un webhook

​Passaggio 5: Testa il tuo agente

​Passaggi successivi

Aggiungi strumenti funzione

Effettua chiamate in uscita

Gestisci i webhook

Riferimento API completo

Passaggio 1: Ottieni una chiave API

Passaggio 2: Crea un agente

Passaggio 3: Effettua il provisioning di un numero di telefono

Passaggio 4 (facoltativo): Configura un webhook

Passaggio 5: Testa il tuo agente

Passaggi successivi