Brug dine egne numre (VoIP, API)

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

Godkendte ThunderPhone-numre kan foretage udgående opkald og køre kampagner. Hvis du foretrækker at bruge numre, du ejer, via din egen VoIP-udbyder, guider denne vejledning dig gennem forbindelsesforløbet: test legitimationsoplysninger → opret forbindelse → importér numre → bekræft.

Understøttede udbydere#

1. Test legitimationsoplysninger#

Før du opretter en vedvarende VoIP-forbindelse, skal du teste udbyderens legitimationsoplysninger for at bekræfte, at de virker. Dette returnerer et verification_evidence_id, som du sender videre til oprettelsestrinnet, så legitimationsoplysningerne ikke bliver opkrævet 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 (trunk-tildeling, IP-tilladelsesliste, autorisation til udgående opkald), og prøv igen.

2. Opret forbindelsen#

Send det verification_evidence_id, du lige har fået:

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

Svaret er et VoipConnection-objekt med status="connected". Legitimationsoplysninger og andre hemmelige forbindelsesværdier gemmes på serveren og returneres aldrig i klartekst af efterfølgende GET-anmodninger — for at rotere dem skal du køre en ny test og PATCH med det nye bevis.

Twilio-underkonti#

En Twilio-forbindelse er knyttet til den enkelte Twilio-konto, hvis Account SID og Auth Token den indeholder. Twilio opbevarer telefonnumre og SIP- trunks i hver underkonto, så en forbindelse oprettet med hovedkontoen kun kan se hovedkontoens egne numre, og en eksisterende forbindelse kan ikke senere skiftes til en anden underkonto.

For at få adgang til numre i underkonti skal du oprette én forbindelse pr. underkonto. Dashboardet gør dette for dig: Når du forbinder en hovedkonto med aktive underkonti, viser opsætningsdialogen dem, du markerer dem, du vil bruge, og ThunderPhone opretter en forbindelse (og en SIP-trunk) i hver af dem. Det samme flow er tilgængeligt via API'et:

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

Svaret indeholder én række pr. underkonto med status som created, skipped (allerede forbundet) eller failed samt en error, du kan handle på. Rækkerne er uafhængige, så en fejl i én underkonto blokerer aldrig de andre, og et discovery_id forbliver gyldigt i 30 minutter, så en mislykket række blot kan prøves igen. Underkontotokens læses fra Twilio på registreringstidspunktet og gemmes på den nye forbindelse; de returneres aldrig af API'et. Hver ny forbindelse importerer og verificerer derefter numre på samme måde som en forbindelse, du har oprettet manuelt. Tilføj "enable_transfers": true for også at aktivere opkaldsoverførsler på hver ny forbindelses SIP-trunk; en fejl dér rapporteres i den pågældende forbindelses test_result.transfer_enable_error og får ikke rækken til at fejle.

3. Vis og importér numre#

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

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

Importér derefter dem, 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 number_type="voip" og status="provisioning".

4. Bekræft hvert importeret nummer#

Import registrerer nummeret som tilgængeligt; faktisk viderestilling af opkald gennem det kræver verificering. For udbyderforbindelser (Twilio, Telnyx) kontrollerer det igen udbyderens legitimationsoplysninger og SIP-tilgængelighed. For en manuel SIP-forbindelse forsøger det først et loopback-selvopkald: ThunderPhone foretager et kort testopkald fra nummeret, gennem din SIP- trunk, tilbage til det samme nummer. Hvis det ikke verificerer den indgående rute, går det videre til et kort testopkald fra nummeret, gennem din SIP-trunk, til et ThunderPhone-nummer. Disse tests kontrollerer trunkens brugernavn, adgangskode, transport, udgående routing og indgående levering. Din operatør fakturerer disse opkald som alle andre.

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". Et nummer på din egen Telnyx-konto fortsætter med at modtage indgående opkald, hvis testopkaldet fejler, eller hvis udgående opkald endnu ikke er konfigureret: det får status="active" med voip_verification_status sat til unverified, og svaret angiver hvorfor. Ved fejl beskriver svaret hvad der fejlede — for en manuel trunk er det udbyderens SIP-svar, for eksempel "afviste ThunderPhones legitimationsoplysninger (SIP 401)" eller "kunne ikke route et opkald (SIP 404)" — ret det (legitimationsoplysninger, tilladte kilde-IP'er, en manglende trunk-tildeling i udbyderens dashboard), og prøv igen.

For en manuel SIP-forbindelse med tilladelsesliste fejler testen af indgående opkald også, hvis disse tilladte kilde-IP-adresser ville blokere et reelt indgående opkald.

5. Tildel agenter og modtag et opkald#

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

Roterende legitimationsoplysninger#

Når en udbydernøgle roterer, 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 numre igen.

Næste trin#