ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Developer cookbook

Použite vlastné čísla (VoIP, API)

Pripojte Twilio, Telnyx, SignalWire, Vonage, Plivo alebo akýkoľvek iný SIP trunk cez SIP, importujte telefónne čísla, ktoré už vlastníte, a umožnite hlasovým agentom ThunderPhone prijímať a uskutočňovať hovory cez tieto čísla.

Schválené čísla ThunderPhone môžu uskutočňovať odchádzajúce hovory a spúšťať kampane. Ak chcete používať vlastné čísla prostredníctvom vlastného poskytovateľa VoIP, tento sprievodca vás prevedie postupom pripojenia: otestovať poverenia → vytvoriť pripojenie → importovať čísla → overiť.

Podporovaní poskytovatelia

PoskytovateľID providerPoznámky
TwiliotwilioSID účtu + overovací token; jedno pripojenie na účet alebo podúčet Twilio (pozrite si podúčty Twilio)
TelnyxtelnyxKľúč API; k dispozícii je sprievodca nastavením (setup_method: guided_telnyx)
SignalWiresignalwireBez natívneho pripojenia poskytovateľa; pripojte ho ako manual s predvoľbou SignalWire SIP
VonagevonageBez natívneho pripojenia poskytovateľa; pripojte ho ako manual s predvoľbou Vonage SIP
Manuálny SIPmanualAkýkoľvek SIP trunk vrátane SignalWire, Vonage a Plivo. Ak začnete z jednej z dlaždíc týchto poskytovateľov na paneli, pripojenie je stále manual a vo voľbe sip_config.preset ukladá výber (signalwire, vonage alebo plivo)

1. Otestujte poverenia

Pred vytvorením trvalého pripojenia VoIP otestujte poverenia poskytovateľa, aby ste potvrdili, že fungujú. Tým získate verification_evidence_id, ktoré odovzdáte v kroku vytvorenia, aby sa testovanie poverení neúčtovalo dvakrát.

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

Ak niektorá kontrola zlyhá, hodnota status v odpovedi bude fail a checks zobrazí, ktorý krok zlyhal. Opravte konfiguráciu na strane poskytovateľa (priradenie trunku, zoznam povolených IP adries, autorizácia odchádzajúcich hovorov) a skúste znova.

2. Vytvorte pripojenie

Odošlite práve získané 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..."
  }'

Odpoveď je objekt VoipConnection so stavom status="connected". Prihlasovacie údaje a ďalšie tajné hodnoty pripojenia sa ukladajú na strane servera a nikdy sa nevracajú v otvorenom texte pri následných požiadavkách GET — ak ich chcete obnoviť, vykonajte nový test a PATCH s novým dôkazom.

Podúčty Twilio

Pripojenie Twilio je viazané na jediný účet Twilio, ktorého Account SID a Auth Token obsahuje. Twilio uchováva telefónne čísla a SIP trunky v rámci každého podúčtu, takže pripojenie vytvorené s nadradeným účtom vidí iba vlastné čísla nadradeného účtu a existujúce pripojenie neskôr nemožno prepnúť na iný podúčet.

Ak chcete pracovať s číslami uloženými v podúčtoch, vytvorte jedno pripojenie pre každý podúčet. Dashboard to vykoná za vás: keď pripojíte nadradený účet s aktívnymi podúčtami, dialóg nastavenia ich zobrazí, vy označíte požadované podúčty a ThunderPhone vytvorí pripojenie (a SIP trunk) v každom z nich. Rovnaký postup je dostupný aj cez API:

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

Odpoveď obsahuje jeden riadok pre každý podúčet so stavom status created, skipped (už pripojené) alebo failed spolu s chybou error, na základe ktorej môžete konať. Riadky sú nezávislé, takže zlyhanie v jednom podúčte nikdy neblokuje ostatné a discovery_id zostáva platné 30 minút, takže neúspešný riadok môžete jednoducho skúsiť znova. Tokeny podúčtov sa načítajú z Twilio v čase zisťovania a uložia sa do nového pripojenia; rozhranie API ich nikdy nevracia. Každé nové pripojenie potom importuje a overuje čísla presne rovnako ako pripojenie vytvorené ručne. Pridajte "enable_transfers": true, aby ste tiež zapli presmerovanie hovorov pre SIP trunk každého nového pripojenia; zlyhanie sa tam zaznamená v test_result.transfer_enable_error daného pripojenia a nespôsobí zlyhanie riadku.

3. Zobrazte a importujte čísla

Skontrolujte čísla viditeľné pre vaše prihlasovacie údaje, ktoré ešte nie sú v organizácii ThunderPhone:

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

Potom importujte tie, ktoré chcete:

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

Každý import sa vo vašej organizácii stane zdrojom telefónneho čísla s number_type="voip" a status="provisioning".

Zachovajte si vlastné smerovanie hovorov

V službe Twilio import umiestni číslo na SIP trunk ThunderPhone vo vašom účte; v službe Telnyx priradí číslo k SIP pripojeniu ThunderPhone. V oboch prípadoch potom každý hovor smeruje priamo k vášmu agentovi.

Ak chcete hovory smerovať sami (napríklad najprv nechať zazvoniť konkrétnej osobe a poslať hovor agentovi iba v prípade, že neodpovie), po importe zmeňte nastavenia hovorov čísla u svojho poskytovateľa alebo číslo importujte cez API s "call_routing": "customer", aby ich ThunderPhone vôbec nemenil. ThunderPhone ich nikdy nezmení späť. Ak má odpovedať agent, pošlite hovor na SIP adresu čísla:

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

Odosielanie správ cez číslo funguje v oboch prípadoch rovnako. Test prichádzajúceho hovoru zavolá na číslo, takže sa spojí s tým, komu vaše smerovanie hovorov odosiela hovory ako prvému.

Presun čísla medzi pripojeniami

Import čísla, ktoré už je v inom z vašich pripojení, ho presunie do nového pripojenia spolu s jeho agentmi a históriou. Číslo, ktoré pripojenie Twilio alebo Telnyx smeruje do ThunderPhone, treba najprv odstrániť z daného pripojenia, pretože jeho poskytovateľ by tam naďalej smeroval hovory.

4. Overte každý importovaný telefónny číslo

Importovaním sa číslo zaregistruje ako dostupné; skutočné smerovanie hovorov cez neho vyžaduje overenie. Pri pripojeniach poskytovateľov (Twilio, Telnyx) sa tým opätovne overia prihlasovacie údaje poskytovateľa a dostupnosť SIP. Pri pripojení manuálny SIP sa najprv skúsi spätné volanie v rámci slučky: ThunderPhone uskutoční krátky testovací hovor z daného čísla, cez váš SIP trunk, späť na to isté číslo. Ak sa tým neoverí prichádzajúca cesta, systém použije krátky testovací hovor z daného čísla, cez váš SIP trunk, na číslo ThunderPhone. Tieto testy kontrolujú používateľské meno trunku, heslo, prenos, odchádzajúce smerovanie a doručenie prichádzajúcich hovorov. Váš operátor tieto hovory účtuje rovnako ako všetky ostatné.

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

Po úspešnom overení sa voip_verification_status zmení na verified a číslo prejde do stavu status="active". Číslo vo vašom vlastnom účte Telnyx naďalej prijíma prichádzajúce hovory, ak jeho testovací hovor zlyhá alebo ak odchádzajúce hovory ešte nie sú nastavené: prejde do stavu status="active" s hodnotou voip_verification_status nastavenou na unverified a odpoveď uvedie dôvod. Pri zlyhaní odpoveď presne uvádza, čo zlyhalo — pri manuálnom trunku ide o SIP odpoveď operátora, napríklad "odmietol poverenia ThunderPhone (SIP 401)" alebo "nepodarilo sa smerovať hovor (SIP 404)" — opravte to (poverenia, povolené zdrojové IP adresy, chýbajúce priradenie trunku v paneli poskytovateľa) a zavolajte znova.

Pri manuálnom SIP pripojení so zoznamom povolených adries test prichádzajúceho hovoru zlyhá aj vtedy, ak by tieto povolené zdrojové IP adresy blokovali skutočný prichádzajúci hovor. Ak v zozname povolených adries používate IP adresy relé ThunderPhone, zahrňte všetky IP adresy relé, ktoré vám ThunderPhone poskytuje pre vaše nastavenie.

5. Priraďte agentov a prijmite hovor

Po overení čísla priradíte agentov pre prichádzajúce/odchádzajúce hovory rovnako ako pri čísle ThunderPhone. Pozrite si Spracovanie prichádzajúcich hovorov a Uskutočňovanie odchádzajúcich hovorov.

Hovory z čísel ThunderPhone môžu tiež volať na destinácie mimo USA a Kanady, ak má ThunderPhone sadzbu pre danú krajinu a typ linky. Tieto hovory sa účtujú podľa sadzby pre danú destináciu.

Obnova prihlasovacích údajov

Keď sa kľúč poskytovateľa obnoví, znova vykonajte postup testovania a následnej aktualizácie:

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

Pripojenie zostane zachované — čísla nie je potrebné znova importovať. V postupe opätovného pripojenia na paneli môžete bezpečne zadať nový kľúč operátora bez nahradenia celého uloženého objektu prihlasovacích údajov vo forme obyčajného textu.


Ďalšie kroky