ThunderPhone v3 je dostupan.Postavite sve sami, već od 2 ¢/min.Pročitajte objavu

Developer cookbook

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

Pružateljprovider IDNapomene
TwiliotwilioSID računa + autentikacijski token; jedna veza po Twilio računu ili podračunu (pogledajte Twilio podračuni)
TelnyxtelnyxAPI ključ; dostupno je vođeno uvođenje (setup_method: guided_telnyx)
SignalWiresignalwireNema izvorne veze s pružateljem; povežite ga kao manual s unaprijed postavljenom konfiguracijom SignalWire SIP-a
VonagevonageNema izvorne veze s pružateljem; povežite ga kao manual s unaprijed postavljenom konfiguracijom Vonage SIP-a
Ručni SIPmanualBilo koji SIP trunk, uključujući SignalWire, Vonage i Plivo. Ako započnete s jednom od pločica tih pružatelja na nadzornoj ploči, veza je i dalje manual i pohranjuje odabir u sip_config.preset (signalwire, vonage ili plivo)

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" }
  }'
Response
{
  "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 i druge tajne vrijednosti veze pohranjuju se na poslužitelju i nikada se ne vraćaju kao običan tekst u naknadnim GET zahtjevima — za rotaciju pokrenite novi test i izvršite PATCH s novim dokazom.

Twilio podračuni

Twilio veza povezana je s jednim Twilio računom čije Account SID i Auth Token podatke sadrži. Twilio čuva telefonske brojeve i SIP trunkove unutar svakog podračuna, stoga veza uspostavljena s nadređenim računom vidi samo vlastite brojeve nadređenog računa, a postojeću vezu kasnije nije moguće prebaciti na drugi podračun.

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

Zadržite vlastito usmjeravanje poziva

Na Twiliou uvoz postavlja broj na ThunderPhoneov SIP trunk na vašem računu; na Telnyxu dodjeljuje broj ThunderPhoneovoj SIP vezi. U svakom slučaju, svaki poziv zatim ide izravno vašem agentu.

Ako umjesto toga želite sami usmjeravati pozive (na primjer, prvo zazvoniti osobi i poslati poziv agentu samo ako se ne javi), nakon uvoza promijenite glasovne postavke broja kod svojeg pružatelja usluge ili uvezite putem API-ja s "call_routing": "customer" kako ih ThunderPhone uopće ne bi promijenio. ThunderPhone ih nikada ne vraća na prethodne postavke. Da bi agent odgovorio, pošaljite poziv na SIP adresu broja:

<Response>
  <Dial>
    <Sip>sip:+15550001234@sip.thunderphone.com</Sip>
  </Dial>
</Response>

Slanje poruka putem broja funkcionira jednako u oba slučaja. Test dolaznog poziva poziva broj, pa stiže do onoga kome vaše usmjeravanje prvo šalje pozive.

Premještanje broja između veza

Uvoz broja koji je već na jednoj od vaših drugih veza premješta ga na novu vezu, zajedno s njegovim agentima i poviješću. Broj koji Twilio ili Telnyx veza šalje ThunderPhoneu prvo se mora ukloniti s te veze jer bi njegov pružatelj usluge nastavio slati pozive tamo.

4. Provjerite svaki uvezeni broj

Uvozom se broj registrira kao dostupan; za stvarno usmjeravanje poziva preko njega potrebna je provjera. Za veze s pružateljima usluga (Twilio, Telnyx) time se ponovno provjeravaju vjerodajnice pružatelja i dostupnost SIP-a. Za ručni SIP spoj najprije se pokušava povratni poziv na isti broj: ThunderPhone upućuje kratki probni poziv s broja, preko vašeg SIP trunka, natrag na isti broj. Ako se time ne potvrdi dolazna putanja, sustav prelazi na kratki probni poziv s broja, preko vašeg SIP trunka, na ThunderPhone broj. Ovi testovi provjeravaju korisničko ime trunka, lozinku, prijenos, odlazno usmjeravanje i dolaznu isporuku. Vaš operater naplaćuje te pozive kao i sve druge.

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.

Za ručnu SIP vezu s popisom dopuštenih izvora test dolaznog poziva također ne uspijeva ako bi ti IP-ovi dopuštenih izvora blokirali stvarni dolazni poziv. Ako u popisu dopuštenih izvora koristite IP-jeve ThunderPhone releja, uključite svaki IP releja koji vam ThunderPhone pruža za vašu postavku.

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.

Pozivi s brojeva ThunderPhone mogu birati i odredišta izvan SAD-a i Kanade kada ThunderPhone ima cijenu za tu državu i vrstu linije. Ti se pozivi naplaćuju po cijeni odredišta.

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 aktivna — nema potrebe ponovno uvoziti brojeve. U tijeku ponovnog povezivanja na nadzornoj ploči možete sigurno unijeti novi ključ operatera bez zamjene cijelog pohranjenog objekta vjerodajnica u običnom tekstu.


Sljedeći koraci