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#

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

{
  "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 sa ukladajú na serveri a následné požiadavky GET ich nikdy nevrátia ako obyčajný text — ak ich chcete zmeniť, spustite nové test a vykonajte PATCH s novými údajmi na overenie.

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

{
  "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".

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 zdrojov zlyhá test prichádzajúceho hovoru aj vtedy, ak by tieto povolené zdrojové IP adresy blokovali skutočný prichádzajúci hovor.

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.

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 zostáva zachované — čísla nemusíte importovať znova.

Ďalšie kroky#