Developer cookbook

Brug dine egne numre (VoIP, API)

Forbind Twilio eller Telnyx — eller enhver SIP-trunk — importér de telefonnumre, du allerede ejer, og lad ThunderPhone-agenter besvare og foretage opkald på dem.

Demonumre er fine til prototyper, men produktionstrafik bør bruge numre, du ejer, gennem din egen VoIP-udbyder. Denne vejledning gennemgår flowet i tre trin: test adgangsoplysninger → opret forbindelse → importer numre → verificer.

Understøttede udbydere#

1. Test adgangsoplysninger#

Før du opretter en gemt VoIP-forbindelse, skal du teste udbyderens adgangsoplysninger for at bekræfte, at de virker. Dette returnerer et verification_evidence_id, som du sender til oprettelsestrinnet, så adgangsoplysningerne ikke bliver debiteret dobbelt for test.

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 kontrol fejler, vil responsens status være fail, og checks vil vise, hvilket trin der fejlede. Ret konfigurationen hos udbyderen (tildeling af trunk, IP-tilladelsesliste, autorisation til udgående opkald), og prøv igen.

2. Opret forbindelsen#

Send det verification_evidence_id, du lige har modtaget:

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". Adgangsoplysninger gemmes på serveren og returneres aldrig i klartekst af efterfølgende GET-anmodninger — for at udskifte dem skal du køre en ny test og PATCH med det nye bevis.

3. Vis og importer numre#

Se de numre, der er synlige med dine adgangsoplysninger, og som ikke allerede er i en ThunderPhone-organisation:

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

Importer derefter de numre, du vil bruge:

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 bliver til en telefonnummerressource i din organisation med source="voip" og status="provisioning".

4. Bekræft hvert importeret nummer#

Import registrerer nummeret som tilgængeligt; faktisk viderestilling af opkald gennem det kræver en tovejskontrol (indgående opkaldstest + udgående autorisationskontrol).

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

Ved succes skifter voip_verification_status til verified, og nummeret får status="active". Ved fejl angiver svaret præcist, hvad der mislykkedes — ret det (ofte en manglende trunk-tildeling i udbyderens dashboard), og kald igen.

5. Tildel agenter, og foretag et opkald#

Når nummeret er bekræftet, tildeler du indgående / udgående agenter på samme måde som for et demonummer. Se Håndter indgående opkald og Foretag udgående opkald.

Rotation af legitimationsoplysninger#

Når en udbydernøgle roteres, skal du køre test-og-opdater-flowet igen:

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

Forbindelsen forbliver på plads — du behøver ikke importere numrene igen.

Næste trin#