Developer cookbook

Ta med dine egne numre (VoIP, API)

Koble til Twilio eller Telnyx — eller en hvilken som helst SIP-trunk — importer telefonnumrene du allerede eier, og la ThunderPhone-stemmeagenter svare på og ringe fra dem.

Demonumre fungerer fint for prototyping, men produksjonstrafikk bør bruke numre du eier gjennom din egen VoIP-leverandør. Denne veiledningen tar deg gjennom flyten i tre trinn: test tilgangsopplysninger → opprett tilkobling → importer numre → verifiser.

Støttede leverandører#

1. Test tilgangsopplysninger#

Før du oppretter en vedvarende VoIP-tilkobling, tester du leverandørens tilgangsopplysninger for å bekrefte at de fungerer. Dette returnerer en verification_evidence_id som du sender til opprettelsestrinnet, slik at tilgangsopplysningene ikke blir belastet to ganger for testing.

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

Hvis en kontroll feiler, blir status i responsen fail, og checks viser hvilket trinn som feilet. Rett opp konfigurasjonen hos leverandøren (trunktilordning, IP-tillatelsesliste, autorisasjon for utgående samtaler) og prøv på nytt.

2. Opprett tilkoblingen#

Send verification_evidence_id-en du nettopp fikk:

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

Responsen er et VoipConnection-objekt med status="connected". Tilgangsopplysninger lagres på serversiden og returneres aldri i klartekst av etterfølgende GET-forespørsler — for å rotere dem, kjør en ny test og PATCH med det nye verifiseringsgrunnlaget.

3. Vis og importer numre#

Se gjennom numrene som er tilgjengelige med tilgangsopplysningene dine, og som ikke allerede finnes i en ThunderPhone-organisasjon:

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

Importer deretter numrene du vil ha:

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

Hver import blir en telefonnummerressurs i organisasjonen din med source="voip" og status="provisioning".

4. Bekreft hvert importerte nummer#

Import registrerer nummeret som tilgjengelig; faktisk ruting av samtaler gjennom det krever en tur-retur-bekreftelse (innkommende oppringingstest + utgående autorisasjonstest).

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

Ved suksess endres voip_verification_status til verified, og nummeret får status="active". Ved feil angir svaret hva som feilet — rett det (ofte en manglende trunktilordning i leverandørens kontrollpanel) og kall på nytt.

5. Tilordne agenter og ta imot en samtale#

Når nummeret er bekreftet, tilordner du innkommende / utgående agenter på samme måte som for et demonummer. Se Håndter innkommende samtaler og Foreta utgående samtaler.

Rotering av legitimasjon#

Når en leverandørnøkkel roteres, kjører du test-og-oppdater-flyten på nytt:

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

Tilkoblingen beholdes — du trenger ikke importere numrene på nytt.

Neste steg#