Developer cookbook

Aduceți-vă propriile numere (VoIP, API)

Conectați Twilio sau Telnyx — sau orice trunchi SIP — importați numerele de telefon pe care le dețineți deja și permiteți agenților ThunderPhone să răspundă și să inițieze apeluri folosindu-le.

Numerele demo sunt potrivite pentru prototipare, dar traficul de producție ar trebui să folosească numere pe care le dețineți prin propriul furnizor VoIP. Acest ghid vă prezintă fluxul în trei pași: 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 arăta la ce pas a apărut problema. Corectați configurația de la furnizor (alocarea trunkului, lista de IP-uri permise, autorizarea apelurilor de ieșire) și reîncercați.

2. Creați conexiunea#

Transmiteți verification_evidence_id pe care tocmai l-ați primit:

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". Acreditările sunt stocate pe server și nu sunt returnate niciodată în text simplu de solicitările GET ulterioare — pentru rotație, executați un nou test și PATCH cu noile dovezi.

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

Inspectați numerele vizibile pentru acreditările dumneavoastră 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 source="voip" și status="provisioning".

4. Verificați fiecare număr importat#

Importarea înregistrează numărul ca fiind disponibil; rutarea efectivă a apelurilor prin acesta necesită o verificare dus-întors (verificare de apelare la intrare + sondă de autorizare pentru apeluri de ieșire).

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 trece la verified, iar numărul intră în status="active". La eșec, răspunsul precizează ce nu a reușit — remediați problema (adesea o alocare lipsă a trunkului în tabloul de bord al furnizorului) și apelați din nou.

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 demo. Consultați Gestionați apelurile de intrare și Inițiați apeluri de ieșire.

Rotirea acreditărilor#

Când cheia unui furnizor este rotită, rulați din nou fluxul de testare-apoi-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 activă — nu este necesar să reimportați numerele.

Pașii următori#