Aduceți propriile numere (VoIP, API)

Conectați Twilio, Telnyx, SignalWire, Vonage, Plivo sau orice alt trunk SIP prin SIP, importați numerele de telefon pe care le dețineți deja și permiteți agenților ThunderPhone să răspundă la apeluri și să inițieze apeluri de pe acestea.

Numerele ThunderPhone aprobate pot efectua apeluri de ieșire și rula campanii. Dacă preferați să utilizați numere pe care le dețineți prin propriul furnizor VoIP, acest ghid vă prezintă fluxul de conectare: testați acreditările → creați conexiunea → importați numerele → verificați.

Furnizori acceptați#

1. Testați acreditările#

Înainte de a crea o conexiune VoIP persistentă, verificați acreditările furnizorului pentru a confirma că funcționează. Aceasta returnează un verification_evidence_id pe care îl transmiteți la pasul de creare, astfel încât acreditările să nu fie taxate de două ori pentru testare.

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

Dacă oricare verificare eșuează, status din răspuns va fi fail, iar checks va indica pasul care a eșuat. Corectați configurația de partea furnizorului (alocarea trunkului, lista de IP-uri permise, autorizarea apelurilor de ieșire) și încercați din nou.

2. Creați conexiunea#

Transmiteți verification_evidence_id pe care tocmai l-ați obținut:

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

Răspunsul este un obiect VoipConnection cu status="connected". Credențialele și alte valori secrete ale conexiunii sunt stocate pe server și nu sunt niciodată returnate în text simplu de GET-urile ulterioare — pentru rotație, executați un nou test și PATCH cu noile dovezi.

Subconturi Twilio#

O conexiune Twilio este asociată cu un singur cont Twilio, ale cărui Account SID și Auth Token le conține. Twilio păstrează numerele de telefon și trunchiurile SIP în fiecare subcont, astfel încât o conexiune creată cu contul părinte vede doar numerele proprii ale părintelui, iar o conexiune existentă nu poate fi comutată ulterior la un alt subcont.

Pentru a accesa numerele deținute în subconturi, creați câte o conexiune pentru fiecare subcont. Tabloul de bord face acest lucru pentru dumneavoastră: când conectați un cont părinte care are subconturi active, dialogul de configurare le listează, bifați cele dorite, iar ThunderPhone creează o conexiune (și un trunchi SIP) în fiecare dintre ele. Același flux este disponibil prin 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..."]}'

Răspunsul conține câte un rând pentru fiecare subcont, cu status created, skipped (deja conectat) sau failed, precum și un error pe baza căruia puteți acționa. Rândurile sunt independente, astfel încât o eroare într-un subcont nu le blochează niciodată pe celelalte, iar un discovery_id rămâne valabil timp de 30 de minute, astfel încât un rând eșuat poate fi pur și simplu reîncercat. Tokenurile subconturilor sunt citite din Twilio la momentul descoperirii și stocate în noua conexiune; acestea nu sunt returnate niciodată de API. Fiecare conexiune nouă importă apoi și verifică numerele exact ca o conexiune creată manual. Adăugați "enable_transfers": true pentru a activa și transferurile de apeluri pentru trunchiul SIP al fiecărei conexiuni noi; o eroare apărută acolo este raportată în test_result.transfer_enable_error al conexiunii respective și nu marchează rândul ca eșuat.

3. Listați și importați numere#

Inspectați numerele vizibile pentru datele dumneavoastră de autentificare care nu sunt deja într-o organizație ThunderPhone:

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

Apoi importați-le pe cele dorite:

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

Fiecare import devine o resursă de număr de telefon în organizația dumneavoastră, cu number_type="voip" și status="provisioning".

4. Verificați fiecare număr importat#

Importul înregistrează numărul ca fiind disponibil; rutarea efectivă a apelurilor prin acesta necesită verificare. Pentru conexiunile prin furnizor (Twilio, Telnyx), aceasta verifică din nou acreditările furnizorului și accesibilitatea SIP. Pentru o conexiune SIP manuală, încearcă mai întâi un apel automat în buclă: ThunderPhone plasează un apel de test scurt de la număr, prin trunchiul SIP al dumneavoastră, înapoi la același număr. Dacă aceasta nu verifică ruta de intrare, revine la un apel de test scurt de la număr, prin trunchiul SIP al dumneavoastră, către un număr ThunderPhone. Aceste teste verifică numele de utilizator, parola, transportul, rutarea de ieșire și livrarea apelurilor de intrare ale trunchiului. Operatorul dumneavoastră facturează aceste apeluri la fel ca pe oricare altele.

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

La reușită, voip_verification_status se schimbă în verified, iar numărul trece în status="active". Un număr din propriul dumneavoastră cont Telnyx continuă să preia apeluri de intrare atunci când apelul său de test eșuează sau când apelurile de ieșire nu sunt încă configurate: devine status="active" cu voip_verification_status setat la unverified, iar răspunsul explică motivul. În caz de eșec, răspunsul precizează ce nu a funcționat — pentru un trunk manual, acesta este răspunsul SIP al operatorului, de exemplu „a respins acreditările ThunderPhone (SIP 401)” sau „nu a putut ruta un apel (SIP 404)” — remediați problema (acreditări, adrese IP sursă permise, o asociere de trunk lipsă în tabloul de bord al furnizorului) și apelați din nou.

Pentru o conexiune SIP manuală inclusă pe lista de permisiuni, testul apelurilor de intrare eșuează și dacă acele IP-uri sursă permise ar bloca un apel de intrare real.

5. Alocați agenți și preluați un apel#

După verificarea numărului, alocați agenți pentru apeluri de intrare / ieșire în același mod ca pentru un număr ThunderPhone. Consultați Gestionarea apelurilor de intrare și Inițierea apelurilor de ieșire.

Rotirea datelor de autentificare#

Când o cheie de furnizor este rotită, reluați fluxul de testare și actualizare:

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

Conexiunea rămâne configurată — nu este necesar să reimportați numerele.

Pașii următori#