> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guida rapida (API)

> Rispondi alla tua prima chiamata telefonica con un agente AI in quattro chiamate REST.

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

<Info>
  Ti serve un [account ThunderPhone](https://app.thunderphone.com).
  La registrazione è gratuita e richiede meno di un minuto. Preferisci fare clic anziché usare curl?
  La [guida rapida della dashboard](/it/quickstart-dashboard) porta alla stessa
  prima chiamata senza scrivere codice.
</Info>

## Passaggio 1: Ottieni una chiave API

<Steps>
  <Step title="Accedi">
    Apri [app.thunderphone.com](https://app.thunderphone.com).
  </Step>

  <Step title="Vai a Chiavi">
    Nella dashboard, vai a **Organizzazione → Chiavi**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  Bloccato? [Crea una chiave API del server](/it/guides/api-keys) illustra
  questo flusso passo per passo e il copilota integrato può
  evidenziare ogni controllo per te in tempo reale.
</Tip>

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.

<CodeGroup>
  ```bash cURL theme={null}
  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 theme={null}
  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 theme={null}
  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);
  ```
</CodeGroup>

<Tip>
  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](/api-reference/agents#product-tiers-at-a-glance) per il confronto
  completo.
</Tip>

## 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](/api-reference/voip-connections).)

<CodeGroup>
  ```bash cURL theme={null}
  # 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 Python theme={null}
  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"])
  ```
</CodeGroup>

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.

```bash theme={null}
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](/it/webhooks/overview)).

## 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:

```bash theme={null}
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 theme={null}
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

<CardGroup cols={2}>
  <Card title="Aggiungi strumenti funzione" icon="screwdriver-wrench" href="/it/tools/overview">
    Consenti al tuo agente di chiamare le tue API durante una conversazione.
  </Card>

  <Card title="Effettua chiamate in uscita" icon="arrow-up-right" href="/api-reference/outbound-calls">
    Avvia chiamate dal tuo codice.
  </Card>

  <Card title="Gestisci i webhook" icon="bolt" href="/it/webhooks/overview">
    Reagisci agli eventi delle chiamate in tempo reale.
  </Card>

  <Card title="Riferimento API completo" icon="book" href="/api-reference/introduction">
    Ogni endpoint pubblico, documentato.
  </Card>
</CardGroup>