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

Pripojte Twilio alebo Telnyx — prípadne akýkoľvek SIP trunk — importujte telefónne čísla, ktoré už vlastníte, a umožnite hlasovým agentom ThunderPhone prijímať a uskutočňovať hovory prostredníctvom nich.

Čísla ThunderPhone pokrývajú prichádzajúce hovory, no odchádzajúce hovory a kampane vyžadujú čísla, ktoré vlastníte prostredníctvom vlastného poskytovateľa VoIP. Táto príručka vás prevedie trojkrokovým postupom: otestovať prihlasovacie údaje → vytvoriť pripojenie → importovať čísla → overiť.

Podporovaní poskytovatelia#

1. Otestujte prihlasovacie údaje#

Pred vytvorením trvalého pripojenia VoIP otestujte prihlasovacie údaje poskytovateľa, aby ste potvrdili, že fungujú. Týmto získate verification_evidence_id, ktoré odovzdáte v kroku vytvorenia, aby sa za testovanie prihlasovacích údajov 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 to znova.

2. Vytvorte pripojenie#

Odovzdajte verification_evidence_id, ktoré ste práve získali:

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 pri následných požiadavkách GET sa nikdy nevracajú v otvorenom texte — ak ich chcete zmeniť, spustite nové test a vykonajte PATCH s novým dôkazom.

Podúčty Twilio#

Pripojenie Twilio je viazané na jeden účet Twilio, ktorého Account SID a Auth Token obsahuje. Twilio uchováva telefónne čísla a SIP trunky v rámci jednotlivých podúčtov, 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 (aktualizácia sa zamietne, pretože SIP trunk pripojenia sa nachádza v pôvodnom účte).

Ak chcete pristupovať k číslam v podúčtoch, vytvorte jedno pripojenie pre každý podúčet. Ovládací panel to urobí za vás: keď pripojíte nadradený účet s aktívnymi podúčtami, dialóg nastavenia ich zobrazí, zaškrtnete tie, ktoré chcete, a ThunderPhone vytvorí pripojenie (a SIP trunk) v každom z nich. Rovnaký postup je k dispozícii 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 ktorú môžete reagovať. 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 zopakovať. Tokeny podúčtov sa načítajú z Twilio pri zisťovaní a uložia sa v novom pripojení; API ich nikdy nevracia. Každé nové pripojenie potom importuje a overuje čísla presne ako pripojenie, ktoré ste vytvorili manuálne.

3. Zobrazte a importujte čísla#

Skontrolujte čísla dostupné 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 source="voip" a status="provisioning".

4. Overte každý importovaný číslo#

Importovaním sa číslo zaregistruje ako dostupné; na skutočné smerovanie hovorov cez neho je potrebné overenie. Pri pripojeniach poskytovateľov (Twilio, Telnyx) sa znova overia poverenia poskytovateľa a dostupnosť SIP. Pri pripojení manuálneho SIP sa uskutoční krátky testovací hovor (niekoľko sekúnd, automaticky ukončený) z čísla, cez váš SIP trunk, na číslo ThunderPhone — tým sa reálne overí používateľské meno, heslo, transport a odchádzajúce smerovanie trunku. Váš operátor tento hovor spoplatní ako každý iný.

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

Po úspechu sa voip_verification_status zmení na verified a číslo prejde do stavu status="active". Pri zlyhaní odpoveď uvedie, čo zlyhalo — pri manuálnom trunku ide o SIP odpoveď operátora, napríklad "rejected ThunderPhone's credentials (SIP 401)" alebo "could not route a call (SIP 404)" — opravte to (poverenia, povolené zdrojové IP adresy, chýbajúce priradenie trunku v paneli poskytovateľa) a zavolajte znova.

5. Priraďte agentov a uskutočnite 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.

Rotácia poverení#

Keď sa kľúč poskytovateľa zmení, znova spustite postup testovania a 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 netreba znova importovať.

Ďalšie kroky#