Verbinden via SIP (geen telefoonnummer)

Stuur oproepen rechtstreeks vanuit je PBX, provider of SIP-applicatie naar een ThunderPhone-spraakagent, met een eenmalige SIP-URI per oproep of een permanent SIP-adres.

Als je eigen systeem al telefoonnummers verwerkt (een PBX, een contactcenterplatform of een carrieraccount waarin je nummers roteert), kun je oproepen via gewone SIP naar een ThunderPhone-spraakagent sturen. Je importeert of koopt geen nummer op ThunderPhone. Je systeem belt een SIP-adres en de agent neemt op.

Er zijn twee soorten SIP-adressen:

Beide typen routeren naar één agent in je organisatie en worden in de Oproepgeschiedenis weergegeven zoals elke andere inkomende oproep.

SIP-URI per oproep#

1. Registreer de oproep#

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 (optioneel) is het nummer dat de beller aan jouw kant heeft gebeld. Het wordt opgeslagen als bestemming van de oproep in de Oproepgeschiedenis, en de agent ziet het als zijn eigen nummer.
• variables (optioneel) vullen {{placeholders}} in de prompt van de agent, op dezelfde manier als bij uitgaande oproepen.
• call_id is de id die de oproep in de Oproepgeschiedenis krijgt (GET /v1/calls/{call_id}) zodra deze verbinding maakt.

2. Bel de URI#

Stuur de oproep binnen 5 minuten naar sip_uri. De URI werkt slechts voor één oproep: zodra een oproep deze heeft gebruikt, is deze verbruikt, zelfs als die oproep snel eindigt.

Met Twilio retourneer je bijvoorbeeld deze TwiML voor de oproep die je wilt doorverbinden:

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

Bel de URI vanuit een PBX als SIP-bestemming. Er zijn geen gebruikersnaam of wachtwoord nodig; het token is de inloggegevens, dus behandel de URI als een wachtwoord totdat deze is gebruikt.

SIP-eindpunt (permanent adres)#

1. Maak het eindpunt#

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. Koppel je systeem eraan#

Configureer een SIP-trunk of bestemming met:

Deze transport- en codecinstellingen gelden ook voor URI's per oproep. Twee netwerkdetails zijn belangrijk voor beide soorten adressen:

• Volg Record-Route. Na de eerste INVITE gaat de rest van de signalering van de oproep (ACK, beëindiging, doorverbindingen) naar de specifieke ThunderPhone-server die antwoordde, die wordt vermeld in de Record-Route-header (sip-1.thunderphone.com of sip-2.thunderphone.com, of het IP-adres daarvan). Als je uitgaande SIP beperkt, sta deze hosts dan ook toe naast sip.thunderphone.com: 172.170.39.202 (sip), 13.86.104.121 (sip-1) en 20.80.98.90 (sip-2).
• Audio gaat elders naartoe. sip.thunderphone.com verwerkt alleen signalering. Sta media (RTP) toe naar de adressen en poorten in het SDP-antwoord.

Elke oproep naar het adres bereikt de agent van het eindpunt, ongeacht welk nummer je beller aan jouw kant heeft gebeld. Je importeert nooit nummers, dus het roteren ervan aan jouw kant vereist geen wijziging in ThunderPhone.

Geef het gebelde nummer door (optioneel)#

Om vast te leggen welk van je nummers de beller heeft gebeld, stuur je het in de INVITE mee in een X-Original-To-header (bijvoorbeeld X-Original-To: +14155550142) of in een standaard Diversion-header. ThunderPhone slaat het op als bestemming van de oproep.

De bestemming wordt in deze volgorde gekozen: de to_number die is opgegeven toen een URI per oproep werd geregistreerd, daarna een nummer in X-Original-To, vervolgens een nummer in Diversion. Als geen hiervan een nummer oplevert, wordt voor een eindpunt sip:agent-12-jhxmginwjx (het adres van het eindpunt) weergegeven, of sip:call voor een URI per oproep.

Met Twilio kun je de header aan de SIP-URI toevoegen: sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142.

Beperk bron-IP's (optioneel)#

Stel allowed_source_cidrs in om naast de gebruikersnaam en het wachtwoord alleen oproepen vanaf je eigen signaleringsadressen te accepteren:

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

Oproepen vanaf elk ander adres worden geweigerd voordat ze de agent bereiken. Gebruik de adressen vanwaar je systeem SIP-signalering verstuurt (voor een carrier zoals Twilio: de gepubliceerde IP-bereiken voor signalering), niet je media-adressen.

Wat bellers en je systeem zien#

• Beller-ID: het gebruikersgedeelte van de From-header wordt opgeslagen als de beller. Een telefoonnummer (cijfers, optioneel met +, spaties, streepjes, punten of haakjes) wordt genormaliseerd naar E.164; al het andere, zoals een SIP-gebruikersnaam, blijft zoals verzonden. Er worden maximaal 32 tekens bewaard en een ontbrekende beller wordt opgeslagen als anonymous.
• Geweigerde oproepen: een onbekende of verlopen URI per oproep krijgt SIP 404 Not Found. Een al gebruikte URI per oproep, een uitgeschakeld eindpunt of een bron buiten de allowlist (inclusief elke UDP-oproep naar een eindpunt met een allowlist) wordt verbroken voordat de agent start: je systeem kan zien dat de oproep mislukt, of dat deze verbinding maakt en direct weer eindigt. Deze weigeringen maken geen item in de oproepgeschiedenis aan. Als je organisatie onvoldoende tegoed heeft of de bestedingslimiet heeft bereikt, wordt de oproep geweigerd en verschijnt deze in de oproepgeschiedenis als een mislukte oproep zonder kosten. Registreer een nieuwe URI om een poging per oproep opnieuw te proberen.
• Doorverbindingen: koude doorverbindingen van de agent werken (ThunderPhone stuurt een SIP REFER, die je systeem moet accepteren). Warme doorverbindingen zijn niet beschikbaar voor oproepen naar SIP-adressen, omdat er geen ThunderPhone-nummer is dat als beller-ID voor het tweede gesprek kan worden weergegeven. Met Twilio verbindt de bovenstaande TwiML de agent, maar verwerkt deze geen doorverbindingen: voeg referUrl="https://YOUR_SERVER/sip-transfer" toe aan de <Dial>, en laat die webhook ReferTransferTarget lezen en TwiML retourneren die het doorverbindingsdoel belt (zie Twilio's SIP REFER-handleiding).
• Sms-berichten: het SIP-adres en het gekozen nummer kunnen geen sms-berichten versturen. De agent kan tijdens een oproep naar een SIP-adres alleen sms'en als deze een afzonderlijk sms-geschikt nummer heeft dat is ingesteld voor sms'en; anders is de sms-tool niet beschikbaar.
• Registratie: ThunderPhone accepteert geen SIP REGISTER. Stuur oproepen naar het adres; registreer je er niet op.

Prijzen#

Oproepen naar SIP-adressen worden gefactureerd tegen het normale tarief per minuut van de agent. Er zijn geen kosten voor een telefoonnummer, omdat geen ThunderPhone-nummer de oproep afhandelt. Je eigen provider factureert zijn deel van de oproep zoals gebruikelijk. Zie Prijzen.

Testen#

1. Maak een URI per oproep of een eindpunt zoals hierboven.
2. Bel dit vanuit je systeem, of vanaf een SIP-softphone (voer voor een eindpunt de gebruikersnaam en het wachtwoord in).
3. Open na het ophangen de oproep onder Oproepen in het dashboard, of haal deze op met GET /v1/calls/{call_id}. Je ziet de beller, de bestemming (zie de volgorde onder "Geef het gekozen nummer door") en het transcript.

API-details: API-referentie voor SIP-adressen.