Donesite vlastite brojeve (VoIP, API)

Povežite Twilio, Telnyx, SignalWire, Vonage, Plivo ili bilo koji drugi SIP trunk putem SIP-a, uvezite telefonske brojeve koje već posjedujete i omogućite glasovnim agentima ThunderPhonea da odgovaraju na pozive i upućuju pozive putem njih.

Odobreni ThunderPhone brojevi mogu upućivati odlazne pozive i pokretati kampanje. Ako radije želite upotrebljavati brojeve koje posjedujete putem vlastitog VoIP pružatelja, ovaj vas vodič provodi kroz tijek povezivanja: testirajte vjerodajnice → izradite vezu → uvezite brojeve → potvrdite.

Podržani pružatelji#

1. Testirajte vjerodajnice#

Prije nego što izradite trajnu VoIP vezu, testirajte vjerodajnice pružatelja kako biste potvrdili da rade. Time se vraća verification_evidence_id koji prosljeđujete koraku izrade kako se vjerodajnice ne bi dvaput naplatile za testiranje.

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

Ako bilo koja provjera ne uspije, status odgovora bit će fail, a checks će pokazati koji korak nije uspio. Ispravite konfiguraciju na strani pružatelja (dodjelu trunka, popis dopuštenih IP adresa, autorizaciju odlaznih poziva) i ponovite pokušaj.

2. Izradite vezu#

Proslijedite verification_evidence_id koji ste upravo dobili:

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

Odgovor je objekt VoipConnection sa statusom status="connected". Vjerodajnice se pohranjuju na poslužitelju i nikada se ne vraćaju u običnom tekstu u naknadnim GET zahtjevima — za rotaciju pokrenite novi test i pošaljite PATCH s novim dokazom.

Twilio podračuni#

Twilio veza vezana je uz jedan Twilio račun čije Account SID i Auth Token sadrži. Twilio čuva telefonske brojeve i SIP trunkove unutar svakog podračuna, pa veza uspostavljena s roditeljskim računom vidi samo vlastite brojeve roditeljskog računa, a postojeća se veza kasnije ne može prebaciti na drugi podračun (ažuriranje se odbija jer SIP trunk veze pripada izvornom računu).

Za pristup brojevima na podračunima izradite jednu vezu po podračunu. Nadzorna ploča to radi umjesto Vas: kada povežete roditeljski račun koji ima aktivne podračune, dijalog za postavljanje prikazuje ih, označite one koje želite, a ThunderPhone izrađuje vezu (i SIP trunk) u svakome od njih. Isti je tijek dostupan putem API-ja:

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

Odgovor sadrži jedan redak po podračunu sa status vrijednosti created, skipped (već povezan) ili failed, uz error na koji možete reagirati. Redci su neovisni, stoga neuspjeh u jednom podračunu nikada ne blokira ostale, a discovery_id ostaje valjan 30 minuta, pa možete jednostavno ponovno pokušati neuspjeli redak. Tokeni podračuna čitaju se iz Twilio pri otkrivanju i pohranjuju na novoj vezi; nikada se ne vraćaju putem API-ja. Svaka nova veza zatim uvozi i potvrđuje brojeve jednako kao veza koju ste ručno izradili. Dodajte "enable_transfers": true kako biste uključili i prijenose poziva za SIP trunk svake nove veze; neuspjeh se prijavljuje u test_result.transfer_enable_error te ne uzrokuje neuspjeh retka.

3. Prikažite i uvezite brojeve#

Pregledajte brojeve vidljive Vašim vjerodajnicama koji još nisu u ThunderPhone organizaciji:

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

Zatim uvezite one koje želite:

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

Svaki uvoz stvara resurs telefonskog broja u vašoj organizaciji s number_type="voip" i status="provisioning".

4. Provjerite svaki uvezeni broj#

Uvoz registrira broj kao dostupan; za stvarno usmjeravanje poziva preko njega potrebna je provjera. Za veze s pružateljima usluge (Twilio, Telnyx) to ponovno provjerava vjerodajnice pružatelja i SIP dostupnost. Za ručnu SIP vezu uspostavlja se kratki probni poziv (nekoliko sekundi, automatski prekinut) s broja, preko vašeg SIP trunka, na ThunderPhone broj — tako se stvarno provjeravaju korisničko ime, lozinka, prijenos i odlazno usmjeravanje trunka. Vaš pružatelj usluge naplaćuje taj poziv kao i svaki drugi.

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

Nakon uspjeha, voip_verification_status mijenja se u verified, a broj prelazi u status="active". Broj na Vašem vlastitom Telnyx računu nastavlja primati dolazne pozive kada njegov testni poziv ne uspije ili odlazni pozivi još nisu postavljeni: postaje status="active" s postavljenim voip_verification_status na unverified, a odgovor navodi razlog. U slučaju neuspjeha odgovor navodi što nije uspjelo — za ručni trunk to je SIP odgovor pružatelja usluge, na primjer "odbijene su vjerodajnice za ThunderPhone (SIP 401)" ili "nije bilo moguće usmjeriti poziv (SIP 404)" — ispravite problem (vjerodajnice, dopuštene izvorne IP adrese, nedostajuću dodjelu trunka na nadzornoj ploči pružatelja usluge) i ponovno pozovite endpoint.

5. Dodijelite agente i primite poziv#

Nakon što je broj provjeren, dodjeljujete glasovne agente za dolazne / odlazne pozive na isti način kao za ThunderPhone broj. Pogledajte Obrada dolaznih poziva i Upućivanje odlaznih poziva.

Rotiranje vjerodajnica#

Kada se ključ pružatelja usluge promijeni, ponovno pokrenite postupak testiranja pa ažuriranja:

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

Veza ostaje na mjestu — nema potrebe ponovno uvoziti brojeve.

Sljedeći koraci#