Developer cookbook

Gebruik je eigen nummers (VoIP, API)

Verbind Twilio of Telnyx — of een willekeurige SIP-trunk — importeer de telefoonnummers die je al hebt en laat ThunderPhone-spraakagenten oproepen beantwoorden en plaatsen.

Demonummers zijn prima voor prototyping, maar productieverkkeer moet nummers gebruiken die je bezit via je eigen VoIP-provider. Deze gids leidt je door de driestapsstroom: toegangsgegevens testen → verbinding maken → nummers importeren → verifiëren.

Ondersteunde providers#

1. Toegangsgegevens testen#

Voordat je een permanente VoIP-verbinding maakt, test je de toegangsgegevens van de provider om te bevestigen dat ze werken. Dit retourneert een verification_evidence_id die je doorgeeft aan de stap voor het maken van de verbinding, zodat de toegangsgegevens niet dubbel worden berekend 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 de respons fail en toont checks welke stap is mislukt. Herstel de configuratie aan de providerkant (trunk- toewijzing, IP-toegangslijst, uitgaande autorisatie) en probeer opnieuw.

2. De verbinding maken#

Geef de verification_evidence_id door die je net hebt ontvangen:

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

De respons is een VoipConnection-object met status="connected". Toegangsgegevens worden aan de serverzijde opgeslagen en worden nooit als platte tekst teruggegeven door volgende GET-aanroepen — voer voor roulatie een nieuwe test uit en gebruik PATCH met het nieuwe bewijs.

3. Nummers weergeven en importeren#

Bekijk de nummers die zichtbaar zijn voor je toegangsgegevens en 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 source="voip" en status="provisioning".

4. Verifieer elk geïmporteerd nummer#

Importeren registreert het nummer als beschikbaar; oproepen er daadwerkelijk via routeren vereist een verificatie met een retourcontrole (inkomende inbelcontrole + uitgaande autorisatiecontrole).

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". Bij een fout beschrijft de respons precies wat er is mislukt — los dit op (vaak een ontbrekende trunktoewijzing in het dashboard van de provider) en roep de endpoint opnieuw aan.

5. Wijs agenten toe en neem een oproep aan#

Zodra het nummer is geverifieerd, wijs je inkomende / uitgaande agenten op dezelfde manier toe als bij een demonummer. Zie Inkomende oproepen afhandelen en Uitgaande oproepen plaatsen.

Roterende inloggegevens#

Wanneer een providersleutel roteert, voer je de test-en-bijwerkstroom 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#