Použijte vlastní čísla (VoIP, API)

Připojte Twilio, Telnyx, SignalWire, Vonage, Plivo nebo jakýkoli jiný SIP trunk přes SIP, importujte telefonní čísla, která již vlastníte, a nechte agenty ThunderPhone na nich přijímat a uskutečňovat hovory.

Schválená čísla ThunderPhone mohou uskutečňovat odchozí hovory a spouštět kampaně. Pokud chcete používat čísla, která vlastníte, prostřednictvím vlastního poskytovatele VoIP, tento průvodce vás provede postupem připojení: otestování přihlašovacích údajů → vytvoření připojení → import čísel → ověření.

Podporovaní poskytovatelé#

1. Otestování přihlašovacích údajů#

Před vytvořením trvale uloženého připojení VoIP otestujte přihlašovací údaje poskytovatele a ověřte, že fungují. Tím získáte verification_evidence_id, který předáte v kroku vytvoření, aby se za testování přihlašovacích údajů 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
  }
}

Pokud některá kontrola selže, hodnota status v odpovědi bude fail a checks zobrazí, který krok selhal. Opravte konfiguraci na straně poskytovatele (přiřazení trunku, seznam povolených IP adres, oprávnění pro odchozí hovory) a zkuste to znovu.

2. Vytvoření připojení#

Předejte právě 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..."
  }'

Odpovědí je objekt VoipConnection se stavem status="connected". Přihlašovací údaje jsou uloženy na serveru a následné požadavky GET je nikdy nevracejí v prostém textu — pro jejich obměnu spusťte nový test a odešlete PATCH s novými ověřovacími údaji.

Podúčty Twilio#

Připojení Twilio je vázáno na jediný účet Twilio, jehož Account SID a Auth Token obsahuje. Twilio uchovává telefonní čísla a SIP trunky v jednotlivých podúčtech, takže připojení vytvořené s nadřazeným účtem vidí pouze vlastní čísla nadřazeného účtu a existující připojení nelze později přepnout na jiný podúčet.

Chcete-li přistupovat k číslům v podúčtech, vytvořte jedno připojení pro každý podúčet. Řídicí panel to provede za vás: když připojíte nadřazený účet s aktivními podúčty, dialog nastavení je zobrazí, vyberete požadované a ThunderPhone v každém z nich vytvoří připojení (a SIP trunk). Stejný postup je dostupný přes 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..."]}'

Odpověď obsahuje jeden řádek pro každý podúčet se status created, skipped (již připojeno) nebo failed a s error, na kterou můžete reagovat. Řádky jsou nezávislé, takže selhání v jednom podúčtu nikdy neblokuje ostatní a discovery_id zůstává platné 30 minut, takže neúspěšný řádek můžete jednoduše zopakovat. Tokeny podúčtů se načtou z Twilio při zjišťování a uloží do nového připojení; API je nikdy nevrací. Každé nové připojení pak importuje a ověřuje čísla stejně jako připojení vytvořené ručně. Přidejte "enable_transfers": true, chcete-li také zapnout přesměrování hovorů pro SIP trunk každého nového připojení; selhání se nahlásí v test_result.transfer_enable_error daného připojení a nezpůsobí selhání řádku.

3. Výpis a import čísel#

Zkontrolujte čísla viditelná pro vaše přihlašovací údaje, která ještě nejsou v organizaci ThunderPhone:

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

Poté importujte požadovaná čísla:

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 se ve vaší organizaci stane zdrojem telefonního čísla s hodnotami number_type="voip" a status="provisioning".

4. Ověřte každé importované číslo#

Importováním se číslo zaregistruje jako dostupné; skutečné směrování hovorů přes něj vyžaduje ověření. U připojení poskytovatelů (Twilio, Telnyx) se tím znovu ověří přihlašovací údaje poskytovatele a dostupnost SIP. U připojení ruční SIP se nejprve zkusí smyčkový samoobslužný hovor: ThunderPhone uskuteční krátký testovací hovor z čísla, přes váš SIP trunk, zpět na stejné číslo. Pokud se tím neověří příchozí cesta, použije se krátký testovací hovor z čísla, přes váš SIP trunk, na číslo ThunderPhone. Tyto testy ověřují uživatelské jméno trunku, heslo, transport, odchozí směrování a doručování příchozích hovorů. Váš operátor tyto hovory účtuje stejně jako jakékoli jiné.

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

Po úspěšném ověření se voip_verification_status změní na verified a číslo přejde do stavu status="active". Číslo ve vašem vlastním účtu Telnyx nadále přijímá příchozí hovory, pokud jeho testovací hovor selže nebo odchozí hovory ještě nejsou nastavené: přejde do stavu status="active" s hodnotou voip_verification_status nastavenou na unverified a odpověď uvede proč. Při selhání odpověď přesně popíše, co nefungovalo — u ručního trunku jde o SIP odpověď operátora, například "odmítl přihlašovací údaje ThunderPhone (SIP 401)" nebo "nepodařilo se směrovat hovor (SIP 404)" — opravte to (přihlašovací údaje, povolené zdrojové IP adresy, chybějící přiřazení trunku v dashboardu poskytovatele) a zavolejte znovu.

U ručního SIP připojení se seznamem povolených adres test příchozího hovoru také selže, pokud by tyto povolené zdrojové IP adresy blokovaly skutečný příchozí hovor.

5. Přiřaďte agenty a přijměte hovor#

Po ověření čísla přiřaďte agenty pro příchozí a odchozí hovory stejným způsobem jako u čísla ThunderPhone. Viz Zpracování příchozích hovorů a Uskutečňování odchozích hovorů.

Obměna přihlašovacích údajů#

Při obměně klíče poskytovatele znovu proveďte postup testování a následné aktualizace:

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

Připojení zůstává beze změny — čísla není nutné znovu importovat.

Další kroky#