Kasuta oma telefoninumbreid (VoIP, API)

Ühenda Twilio või Telnyx — või mis tahes SIP-trunk — impordi juba olemasolevad telefoninumbrid ning lase ThunderPhone

ThunderPhone'i numbrid katavad sissetulevad kõned, kuid väljaminevate kõnede ja kampaaniate jaoks on vaja numbreid, mis kuuluvad sulle sinu enda VoIP-teenusepakkuja kaudu. See juhend kirjeldab kolmeetapilist voogu: testi mandaate → loo ühendus → impordi numbrid → kinnita.

Toetatud teenusepakkujad#

1. Testi mandaate#

Enne püsiva VoIP-ühenduse loomist kontrolli teenusepakkuja mandaate, et kinnitada nende toimivust. See tagastab verification_evidence_id, mille edastad loomise etappi, et testimise eest ei küsitaks tasu kaks korda.

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

Kui mõni kontroll ebaõnnestub, on vastuse status väärtus fail ning checks näitab, milline etapp ebaõnnestus. Paranda teenusepakkuja-poolne seadistus (trunki määramine, IP-aadresside lubatud loend, väljaminevate kõnede autoriseerimine) ja proovi uuesti.

2. Loo ühendus#

Edasta äsja saadud verification_evidence_id:

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

Vastus on VoipConnectioni objekt olekus status="connected". Volitused salvestatakse serveripoolel ja neid ei tagastata järgmiste GET-päringutega kunagi lihttekstina — volituste vahetamiseks käivita uus test ja tee PATCH uue tõendiga.

Twilio alamkontod#

Twilio ühendus on seotud ühe Twilio kontoga, mille Account SID-i ja Auth Tokenit see sisaldab. Twilio hoiab telefoninumbreid ja SIP-trunke iga alamkonto sees, seega näeb põhikontoga loodud ühendus ainult põhikonto enda numbreid ning olemasolevat ühendust ei saa hiljem teisele alamkontole ümber lülitada (värskendus lükatakse tagasi, sest ühenduse SIP-trunk asub algsel kontol).

Alamkontodel olevate numbrite kasutamiseks loo iga alamkonto jaoks üks ühendus. Töölaud teeb selle sinu eest: kui ühendad aktiivsete alamkontodega põhikonto, kuvatakse seadistusdialoogis alamkontode loend, märgid soovitud kontod ja ThunderPhone loob igasse neist ühenduse (ja SIP-trunki). Sama voog on saadaval API kaudu:

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

Vastus sisaldab iga alamkonto kohta ühe rea olekuga status created, skipped (juba ühendatud) või failed ning veaga error, mille põhjal saad tegutseda. Read on sõltumatud, seega ei blokeeri ühe alamkonto tõrge teisi, ning discovery_id jääb kehtima 30 minutiks, nii et ebaõnnestunud rida saab lihtsalt uuesti proovida. Alamkonto tokenid loetakse Twiliost avastamise ajal ja salvestatakse uude ühendusse; neid ei tagastata API kaudu kunagi. Seejärel impordib ja kinnitab iga uus ühendus numbrid täpselt samamoodi nagu käsitsi loodud ühendus.

3. Loetle ja impordi numbrid#

Vaata oma volitustele nähtavaid numbreid, mida ThunderPhone'i organisatsioonis veel pole:

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

Seejärel impordi soovitud numbrid:

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

Iga import muutub sinu organisatsioonis telefoninumbri ressursiks, millel on source="voip" ja status="provisioning".

4. Kontrolli iga imporditud numbrit#

Importimine registreerib numbri saadavana; kõnede tegelik suunamine selle kaudu nõuab kontrollimist. Teenusepakkuja ühenduste (Twilio, Telnyx) puhul kontrollitakse uuesti teenusepakkuja autentimisandmeid ja SIP-i kättesaadavust. Käsitsi seadistatud SIP-i ühenduse puhul tehakse numbrilt lühike testkõne (mõni sekund, katkestatakse automaatselt) numbrilt, sinu SIP-trunki kaudu ThunderPhone'i numbrile — nii kontrollitakse päriselt trunk'i kasutajanime, parooli, transpordi ja väljamineva kõneliikluse suunamist. Sinu operaator arveldab selle kõne nagu mis tahes muu kõne.

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

Õnnestumise korral muutub voip_verification_status väärtuseks verified ja number saab oleku status="active". Ebaõnnestumise korral selgitab vastus, mis ebaõnnestus — käsitsi seadistatud trunk'i puhul on see operaatori SIP-vastus, näiteks "ThunderPhone'i autentimisandmed lükati tagasi (SIP 401)" või "kõnet ei saanud suunata (SIP 404)" — paranda probleem (autentimisandmed, lubatud lähte-IP-aadressid või teenusepakkuja juhtpaneelil puuduv trunk'i määrang) ja tee päring uuesti.

5. Määra häälagendid ja võta kõne vastu#

Kui number on kontrollitud, määra sissetulevate ja väljaminevate kõnede häälagendid samamoodi nagu ThunderPhone'i numbri puhul. Vaata Sissetulevate kõnede haldamine ja Väljaminevate kõnede tegemine.

Autentimisandmete vahetamine#

Kui teenusepakkuja võti muutub, käivita uuesti testi-ja-värskenda töövoog:

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

Ühendus jääb alles — numbreid pole vaja uuesti importida.

Järgmised sammud#