Connettiti tramite SIP (senza numero di telefono)

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:

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#

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"}
  }'

{
  "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.
• 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:

<Response>
  <Dial>
    <Sip>sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp</Sip>
  </Dial>
</Response>

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#

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"}'

{
  "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"
}

2. Indirizza il tuo sistema all'endpoint#

Configura un trunk o una destinazione SIP con:

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:

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.

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 <Dial>, 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).
• 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.

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.