Saját telefonszámok használata (VoIP, API)

Csatlakoztassa a Twiliót, a Telnyxet, a SignalWire-t, a Vonage-ot, a Plivót vagy bármely más SIP-trunkot SIP-en keresztül, importálja a már meglévő telefonszámait, és hagyja, hogy a ThunderPhone ügynökei fogadják és kezdeményezzék rajtuk a hívásokat.

A jóváhagyott ThunderPhone-számokkal kimenő hívásokat kezdeményezhet és kampányokat futtathat. Ha inkább a saját VoIP-szolgáltatóján keresztül szeretné használni a saját számait, ez az útmutató végigvezeti a csatlakoztatási folyamaton: hitelesítő adatok tesztelése → kapcsolat létrehozása → számok importálása → ellenőrzés.

Támogatott szolgáltatók#

1. Hitelesítő adatok tesztelése#

Állandó VoIP-kapcsolat létrehozása előtt ellenőrizze a szolgáltatói hitelesítő adatokat, hogy megbizonyosodjon a működésükről. Ez egy verification_evidence_id értéket ad vissza, amelyet át kell adnia a létrehozási lépésnek, hogy a hitelesítő adatok teszteléséért ne számítsanak fel kétszer díjat.

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

Ha bármelyik ellenőrzés sikertelen, a válasz status értéke fail lesz, és a checks megmutatja, melyik lépés hibásodott meg. Javítsa a szolgáltatói oldali konfigurációt (trönkhozzárendelés, IP-engedélyezési lista, kimenő hívások jogosultsága), majd próbálja újra.

2. A kapcsolat létrehozása#

Adja át az imént kapott verification_evidence_id azonosítót:

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

A válasz egy VoipConnection objektum status="connected" állapotban. A hitelesítő adatok a szerveren tárolódnak, és a későbbi GET kérések soha nem adják vissza őket egyszerű szövegként — cseréjükhöz futtasson egy új test műveletet, majd küldjön PATCH kérést az új bizonyítékkal.

Twilio-alfiókok#

A Twilio-kapcsolat ahhoz az egyetlen Twilio-fiókhoz van kötve, amelynek Account SID azonosítóját és Auth Tokenjét tartalmazza. A Twilio a telefonszámokat és a SIP- trönköket az egyes alfiókokban tárolja, ezért a szülőfiókkal létrehozott kapcsolat csak a szülőfiók saját számait látja, és egy meglévő kapcsolat később nem váltható át másik alfiókra.

Az alfiókokban tárolt számok eléréséhez hozzon létre egy kapcsolatot alfiókonként. Az irányítópult ezt elvégzi Ön helyett: amikor aktív alfiókokkal rendelkező szülőfiókot csatlakoztat, a beállítási párbeszédablak felsorolja őket, Ön kiválasztja a kívántakat, és a ThunderPhone mindegyikben létrehoz egy kapcsolatot (és egy SIP-trönköt). Ugyanez a folyamat az API-n keresztül is elérhető:

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

A válasz minden egyes alfiokhoz egy sort tartalmaz, amelynek status értéke created, skipped (már csatlakoztatva) vagy failed, valamint egy kezelhető error értéket is tartalmaz. A sorok egymástól függetlenek, így az egyik alfiok hibája soha nem blokkolja a többit, a discovery_id pedig 30 percig érvényes marad, ezért egy sikertelen sor egyszerűen újrapróbálható. Az alfiok tokenjeit a ThunderPhone a felderítéskor olvassa ki a Twilio rendszeréből, és az új kapcsolaton tárolja őket; az API soha nem adja vissza őket. Ezután minden új kapcsolat pontosan ugyanúgy importálja és ellenőrzi a számokat, mint egy kézzel létrehozott kapcsolat. Adja hozzá az "enable_transfers": true értéket, hogy az egyes új kapcsolatok SIP-trönkjein a hívásátirányítás is engedélyezve legyen; az ottani hiba az adott kapcsolat test_result.transfer_enable_error mezőjében jelenik meg, és nem teszi sikertelenné a sort.

3. Számok listázása és importálása#

Vizsgálja meg a hitelesítő adatai számára látható, még nem ThunderPhone-szervezetben lévő számokat:

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

Ezután importálja a kívántakat:

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

Minden importált szám telefonszám-erőforrássá válik az Ön szervezetében, number_type="voip" és status="provisioning" értékekkel.

4. Ellenőrizze az egyes importált számokat#

Az importálás a számot elérhetőként regisztrálja; a hívások tényleges irányításához azonban ellenőrzés szükséges. Szolgáltatói kapcsolatok (Twilio, Telnyx) esetén ez újraellenőrzi a szolgáltatói hitelesítő adatokat és a SIP elérhetőségét. manuális SIP kapcsolat esetén először egy visszacsatolt önhívást próbál meg: a ThunderPhone rövid próbahívást indít a számról, az Ön SIP trönkjén keresztül, vissza ugyanarra a számra. Ha ez nem ellenőrzi a bejövő útvonalat, akkor rövid próbahívásra vált a számról, az Ön SIP trönkjén keresztül, egy ThunderPhone-számra. Ezek a tesztek a trönk felhasználónevét, jelszavát, átvitelét, kimenő útválasztását és bejövő kézbesítését ellenőrzik. A szolgáltatója ezeket a hívásokat ugyanúgy számlázza, mint bármely más hívást.

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

Siker esetén a voip_verification_status értéke verified lesz, a szám pedig status="active" állapotba kerül. A saját Telnyx-fiókjában lévő szám továbbra is fogad bejövő hívásokat, ha a teszthívása sikertelen, vagy a kimenő hívások még nincsenek beállítva: ekkor status="active" állapotba kerül, a voip_verification_status értéke pedig unverified lesz, és a válasz megadja az okát. Sikertelenség esetén a válasz részletezi, mi hibázott — kézi trunk esetén ez a szolgáltató SIP-válasza, például "elutasította a ThunderPhone hitelesítő adatait (SIP 401)" vagy "nem sikerült hívást irányítani (SIP 404)" — javítsa a hibát (hitelesítő adatok, engedélyezett forrás-IP-címek, hiányzó trunk-hozzárendelés a szolgáltatói irányítópulton), majd hívja meg újra.

Engedélyezési listán szereplő manuális SIP kapcsolat esetén a bejövőhívás-teszt akkor is sikertelen, ha az Engedélyezett forrás IP-címek blokkolnának egy valódi bejövő hívást.

5. Rendeljen hozzá ügynököket, és fogadjon hívást#

A szám ellenőrzése után ugyanúgy rendelhet hozzá bejövő és kimenő AI-ügynököket, mint egy ThunderPhone-számhoz. Lásd: Bejövő hívások kezelése és Kimenő hívások indítása.

Hitelesítő adatok cseréje#

Amikor egy szolgáltatói kulcs cserélődik, futtassa újra a tesztelés, majd frissítés folyamatát:

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

A kapcsolat változatlanul megmarad — nincs szükség a számok újbóli importálására.

Következő lépések#