Gebruik je eigen nummers (VoIP, API)

Koppel Twilio, Telnyx, SignalWire, Vonage, Plivo en elke andere SIP-trunk via SIP, importeer de telefoonnummers die je al hebt en laat ThunderPhone-spraakagenten oproepen beantwoorden en plaatsen.

Goedgekeurde ThunderPhone-nummers kunnen uitgaande oproepen plaatsen en campagnes uitvoeren. Als je liever nummers gebruikt die je bezit via je eigen VoIP-provider, leidt deze handleiding je door het verbindingsproces: referenties testen → verbinding maken → nummers importeren → verifiëren.

Ondersteunde providers#

1. Referenties testen#

Voordat je een opgeslagen VoIP-verbinding maakt, test je de provider- referenties om te bevestigen dat ze werken. Dit retourneert een verification_evidence_id die je doorgeeft aan de aanmaakstap, zodat de referenties niet dubbel in rekening worden gebracht voor tests.

curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'

{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}

Als een controle mislukt, is de status van het antwoord fail en toont checks welke stap is mislukt. Corrigeer de configuratie aan de providerzijde (toewijzing van trunks, IP-toegangslijst, autorisatie voor uitgaande oproepen) en probeer het opnieuw.

2. Maak de verbinding#

Geef de verification_evidence_id door die je zojuist hebt gekregen:

curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "Acme Telnyx Main",
    "provider":     "telnyx",
    "setup_method": "api_key",
    "credentials":  { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":   { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'

Het antwoord is een VoipConnection-object met status="connected". Inloggegevens worden server-side opgeslagen en bij latere GET-aanvragen nooit als platte tekst geretourneerd — voer om te roteren een nieuwe test uit en gebruik PATCH met het nieuwe bewijs.

Twilio-subaccounts#

Een Twilio-verbinding is gekoppeld aan het specifieke Twilio-account waarvan de Account SID en Auth Token zijn opgeslagen. Twilio bewaart telefoonnummers en SIP- trunks binnen elk subaccount, dus een verbinding die met het hoofdaccount is gemaakt, ziet alleen de eigen nummers van het hoofdaccount, en een bestaande verbinding kan later niet naar een ander subaccount worden overgezet.

Maak voor nummers in subaccounts één verbinding per subaccount. Het dashboard doet dit voor je: wanneer je een hoofdaccount met actieve subaccounts verbindt, worden deze in het insteldialoogvenster weergegeven, vink je de gewenste aan en maakt ThunderPhone in elk account een verbinding (en een SIP-trunk). Dezelfde flow is beschikbaar via de API:

# Discover active subaccounts visible to the parent credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}'

{
  "discovery_id": "7c1e...",
  "parent": { "sid": "ACparent...", "friendly_name": "Acme" },
  "subaccounts": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "already_connected": true,  "connection_id": 5 }
  ]
}

# Create a connection for each selected subaccount
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}'

Het antwoord bevat één rij per subaccount met de status created, skipped (al verbonden) of failed, plus een error waarop je kunt handelen. Rijen zijn onafhankelijk, dus een fout in één subaccount blokkeert de andere nooit. Een discovery_id blijft 30 minuten geldig, zodat je een mislukte rij eenvoudig opnieuw kunt proberen. Tokens van subaccounts worden tijdens de detectie uit Twilio gelezen en opgeslagen in de nieuwe verbinding; ze worden nooit via de API geretourneerd. Elke nieuwe verbinding importeert en verifieert vervolgens nummers precies zoals een verbinding die je handmatig hebt gemaakt. Voeg "enable_transfers": true toe om ook oproepdoorschakelingen in te schakelen voor de SIP-trunk van elke nieuwe verbinding; een fout daarbij wordt gemeld in de test_result.transfer_enable_error van die verbinding en laat de rij niet mislukken.

3. Nummers weergeven en importeren#

Bekijk de nummers die zichtbaar zijn met je inloggegevens en die nog niet in een ThunderPhone-organisatie staan:

curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Importeer vervolgens de nummers die je wilt:

curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'

Elke import wordt een telefoonnummerresource in je organisatie met number_type="voip" en status="provisioning".

4. Verifieer elk geïmporteerd nummer#

Importeren registreert het nummer als beschikbaar; om gesprekken daadwerkelijk erdoorheen te routeren, is verificatie nodig. Voor providerverbindingen (Twilio, Telnyx) worden daarbij de providerreferenties en SIP-bereikbaarheid opnieuw gecontroleerd. Voor een handmatige SIP-verbinding wordt eerst een loopback-zelfoproep geprobeerd: ThunderPhone plaatst een korte testoproep vanaf het nummer, via je SIP- trunk, terug naar hetzelfde nummer. Als daarmee het inkomende pad niet wordt geverifieerd, valt het terug op een korte testoproep vanaf het nummer, via je SIP-trunk, naar een ThunderPhone-nummer. Deze tests controleren de gebruikersnaam, het wachtwoord, transport, uitgaande routering en inkomende aflevering van de trunk. Je provider brengt deze oproepen net als alle andere in rekening.

curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Bij succes verandert voip_verification_status in verified en krijgt het nummer status="active". Een nummer in je eigen Telnyx-account blijft inkomende oproepen ontvangen wanneer de testoproep mislukt of uitgaand verkeer nog niet is ingesteld: het krijgt status="active" met voip_verification_status ingesteld op unverified, en het antwoord vermeldt waarom. Bij een fout geeft het antwoord precies aan wat er is mislukt — voor een handmatige trunk is dat het SIP-antwoord van de provider, bijvoorbeeld "de inloggegevens van ThunderPhone afgewezen (SIP 401)" of "kon een oproep niet routeren (SIP 404)" — los dit op (inloggegevens, toegestane bron-IP-adressen, een ontbrekende trunktoewijzing in het providerdashboard) en probeer opnieuw.

Voor een handmatige SIP-verbinding met een toelatingslijst mislukt de test voor inkomende oproepen ook als die Allowed Source IPs een echte inkomende oproep zouden blokkeren.

5. Wijs agenten toe en neem een oproep aan#

Zodra het nummer is geverifieerd, wijs je inkomende / uitgaande spraakagenten op dezelfde manier toe als aan een ThunderPhone-nummer. Zie Inkomende oproepen afhandelen en Uitgaande oproepen plaatsen.

Referenties roteren#

Wanneer een providersleutel wordt geroteerd, voer je de test-en-updateprocedure opnieuw uit:

# 1. Test the new credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/test ...
 
# 2. PATCH the connection with the new evidence
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "NEW_KEY..." },
    "verification_evidence_id": "fresh-evidence-id"
  }'

De verbinding blijft bestaan — je hoeft nummers niet opnieuw te importeren.

Volgende stappen#