--- title: "Connettiti tramite SIP (senza numero di telefono)" description: "Invia le chiamate a un agente ThunderPhone direttamente dal tuo PBX, operatore o applicazione SIP, con un URI SIP monouso per chiamata o un indirizzo SIP permanente." --- Se il tuo sistema gestisce già i numeri di telefono (un PBX, una piattaforma di contact center o un account operatore in cui ruoti i numeri), puoi inviare le chiamate a un agente ThunderPhone tramite SIP standard. Non devi importare né acquistare un numero su ThunderPhone. Il tuo sistema compone un indirizzo SIP e l'agente risponde. Esistono due tipi di indirizzo SIP: | | **URI SIP per chiamata** | **Endpoint SIP** | |---|---|---| | Aspetto | `sip:c-@sip.thunderphone.com` | `sip:agent--@sip.thunderphone.com` | | Creato con | `POST /v1/calls/register-sip`, una volta per chiamata | `POST /v1/sip-endpoints`, una volta | | Autenticazione | Il token monouso nell'indirizzo | Nome utente e password SIP digest (e, facoltativamente, una allowlist di IP di origine) | | Ideale per | App che chiamano già un'API prima di trasferire una chiamata; variabili per chiamata | PBX e operatori che devono semplicemente "puntare un trunk" verso ThunderPhone | | Valido per | 5 minuti, una chiamata | Finché non lo elimini | Entrambi i tipi instradano verso un agente della tua organizzazione e compaiono nella cronologia delle chiamate come qualsiasi altra chiamata in entrata. ## URI SIP per chiamata ### 1. Registra la chiamata ```bash curl -X POST https://api.thunderphone.com/v1/calls/register-sip \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": 12, "to_number": "+14155550142", "variables": {"customer_name": "Ada"} }' ``` ```json { "call_id": 862197007562, "sip_uri": "sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com", "expires_at": "2026-09-25T21:49:52Z", "agent_id": 12, "to_number": "+14155550142" } ``` - `to_number` (facoltativo) è il numero composto dal chiamante sul tuo lato. Viene memorizzato come destinazione della chiamata nella cronologia delle chiamate e l'agente lo vede come il proprio numero. - `variables` (facoltativo) compilano i `{{placeholders}}` nel prompt dell'agente, come per le [chiamate in uscita](/it/guides/call-variables). - `call_id` è l'id che la chiamata avrà nella cronologia delle chiamate (`GET /v1/calls/{call_id}`) una volta connessa. ### 2. Componi l'URI Invia la chiamata a `sip_uri` entro 5 minuti. L'URI funziona per una sola chiamata: una volta utilizzato da una chiamata, non è più valido, anche se quella chiamata termina rapidamente. Con Twilio, ad esempio, restituisci questo TwiML per la chiamata che vuoi trasferire: ```xml sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp ``` Da un PBX, componi l'URI come destinazione SIP. Non sono necessari nome utente o password; il token è la credenziale, quindi tratta l'URI come una password finché non è stato utilizzato. ## Endpoint SIP (indirizzo permanente) ### 1. Crea l'endpoint ```bash curl -X POST https://api.thunderphone.com/v1/sip-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"agent_id": 12, "name": "Main PBX"}' ``` ```json { "id": 7, "name": "Main PBX", "agent_id": 12, "sip_uri": "sip:agent-12-jhxmginwjx@sip.thunderphone.com", "username": "tp409667538f83", "password": "8mJ0…", "allowed_source_cidrs": [], "status": "active", "created_at": "2026-09-25T21:46:18Z" } ``` La `password` viene restituita una sola volta, quando viene creato l'endpoint. Salvala subito nella configurazione del tuo PBX o operatore. Se la perdi, ruotala con `POST /v1/sip-endpoints/{id}/rotate-password`. ### 2. Indirizza il tuo sistema all'endpoint Configura un trunk o una destinazione SIP con: | Impostazione | Valore | |---|---| | URI SIP | il `sip_uri` dell'endpoint | | Nome utente / password | `username` / `password` (autenticazione digest; ThunderPhone verifica ogni chiamata) | | Trasporto | TCP sulla porta 5060 o TLS sulla porta 5061 (consigliato), oppure UDP sulla porta 5060 | | Codec | G.711 (PCMU/PCMA) o G.722 | Preferisci TCP o TLS. UDP funziona da indirizzi pubblici e dalla maggior parte dei NAT, ma dietro un NAT "simmetrico" (che usa una nuova porta per ogni destinazione) le chiusure delle chiamate e i trasferimenti dell'agente potrebbero non raggiungere il tuo sistema. Anche una lista di autorizzazione degli IP sorgente (sotto) richiede TCP o TLS. Con TLS, la segnalazione SIP resta crittografata anche oltre `sip.thunderphone.com`, fino ai server che gestiscono la chiamata. Queste impostazioni di trasporto e codec si applicano anche agli URI per chiamata. Due dettagli di rete sono importanti per entrambi i tipi di indirizzo: - **Segui Record-Route.** Dopo il primo INVITE, il resto della segnalazione della chiamata (ACK, chiusura, trasferimenti) viene inviato allo specifico server ThunderPhone che ha risposto, indicato nell'header `Record-Route` (`sip-1.thunderphone.com` o `sip-2.thunderphone.com`, oppure il relativo indirizzo IP). Se limiti il SIP in uscita, autorizza questi host oltre a `sip.thunderphone.com`: `172.170.39.202` (`sip`), `13.86.104.121` (`sip-1`) e `20.80.98.90` (`sip-2`). - **L'audio passa altrove.** `sip.thunderphone.com` gestisce solo la segnalazione. Autorizza il traffico multimediale (RTP) verso gli indirizzi e le porte nella risposta SDP. Ogni chiamata a questo indirizzo raggiunge l'agente dell'endpoint, indipendentemente dal numero composto dal chiamante sul tuo lato. Non importi mai numeri, quindi ruotarli sul tuo lato non richiede modifiche in ThunderPhone. ### Trasmetti il numero composto (facoltativo) Per registrare quale dei tuoi numeri ha composto il chiamante, invialo nell'INVITE in un header `X-Original-To` (ad esempio `X-Original-To: +14155550142`) o in un header standard `Diversion`. ThunderPhone lo memorizza come destinazione della chiamata. La destinazione viene scelta in questo ordine: il `to_number` fornito durante la registrazione di un URI per chiamata, poi un numero in `X-Original-To`, quindi uno in `Diversion`. Se nessuno di questi fornisce un numero, viene mostrato come `sip:agent-12-jhxmginwjx` (l'indirizzo dell'endpoint) per un endpoint, oppure `sip:call` per un URI per chiamata. Con Twilio puoi aggiungere l'header all'URI SIP: `sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142`. ### Limita gli IP sorgente (facoltativo) Imposta `allowed_source_cidrs` per accettare chiamate solo dai tuoi indirizzi di segnalazione, oltre al nome utente e alla password: ```bash curl -X PATCH https://api.thunderphone.com/v1/sip-endpoints/7 \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"allowed_source_cidrs": ["203.0.113.0/28"]}' ``` Le chiamate da qualsiasi altro indirizzo vengono rifiutate prima di raggiungere l'agente. Usa gli indirizzi da cui il tuo sistema invia la segnalazione SIP (per un operatore come Twilio, i relativi intervalli IP di segnalazione pubblicati), non i tuoi indirizzi multimediali. La lista di autorizzazione viene verificata solo per le chiamate su TCP o TLS. Un indirizzo sorgente UDP può essere falsificato, quindi un endpoint con una lista di autorizzazione rifiuta ogni chiamata che arriva su UDP. Inviagli le chiamate con `;transport=tcp` (porta 5060) oppure tramite TLS (porta 5061). ## Cosa vedono i chiamanti e il tuo sistema - **ID chiamante:** la parte utente dell'intestazione `From` viene memorizzata come chiamante. Un numero di telefono (cifre, facoltativamente con `+`, spazi, trattini, punti o parentesi) viene normalizzato in E.164; qualsiasi altro valore, ad esempio un nome utente SIP, viene mantenuto come inviato. Vengono conservati al massimo 32 caratteri e un chiamante mancante viene memorizzato come `anonymous`. - **Chiamate rifiutate:** un URI per chiamata sconosciuto o scaduto riceve SIP `404 Not Found`. Un URI per chiamata già utilizzato, un endpoint disabilitato o una sorgente esterna alla allowlist (inclusa qualsiasi chiamata UDP verso un endpoint con allowlist) viene disconnesso prima che l'agente si avvii: il tuo sistema potrebbe vedere la chiamata non riuscire, oppure connettersi e terminare subito. Questi rifiuti non creano una voce nella cronologia chiamate. Se la tua organizzazione non ha più credito o ha raggiunto il limite di spesa, la chiamata viene rifiutata e appare nella cronologia chiamate come chiamata non riuscita senza addebito. Per ritentare un tentativo per chiamata, registra un nuovo URI. - **Trasferimenti:** i trasferimenti a freddo dell'agente funzionano (ThunderPhone invia un SIP `REFER`, che il tuo sistema deve accettare). I trasferimenti con consultazione non sono disponibili per le chiamate a indirizzi SIP, perché non esiste un numero ThunderPhone da mostrare come ID chiamante per la seconda tratta. Con Twilio, il TwiML sopra collega l'agente ma non gestisce i trasferimenti: aggiungi `referUrl="https://YOUR_SERVER/sip-transfer"` a ``, quindi fai in modo che quel webhook legga `ReferTransferTarget` e restituisca TwiML che chiama la destinazione del trasferimento (consulta la [guida SIP REFER di Twilio](https://www.twilio.com/docs/voice/api/refer-to-twilio)). - **Messaggi di testo:** l'indirizzo SIP e il numero chiamato non possono inviare messaggi di testo. L'agente può inviare messaggi durante una chiamata a un indirizzo SIP solo se dispone di un numero separato abilitato agli SMS configurato per l'invio di messaggi; altrimenti il suo strumento SMS non è disponibile. - **Registrazione:** ThunderPhone non accetta SIP `REGISTER`. Invia le chiamate all'indirizzo; non registrarti a esso. ## Prezzi Le chiamate a indirizzi SIP vengono fatturate alla normale tariffa al minuto dell'agente. Non è previsto alcun addebito per il numero di telefono, perché nessun numero ThunderPhone instrada la chiamata. Il tuo operatore fattura normalmente la propria parte della chiamata. Consulta [Prezzi](/it/guides/pricing). ## Provalo 1. Crea un URI per chiamata o un endpoint come descritto sopra. 2. Chiamalo dal tuo sistema o da qualsiasi softphone SIP (per un endpoint, inserisci il nome utente e la password). 3. Dopo aver riagganciato, apri la chiamata in **Chiamate** nella dashboard, oppure recuperala con `GET /v1/calls/{call_id}`. Mostra il chiamante, la destinazione (consulta l'ordine in "Passa il numero chiamato") e la trascrizione. Dettagli API: [riferimento API per gli indirizzi SIP](/api-reference/sip-addresses).