Developer cookbook

Använd dina egna nummer (VoIP, API)

Anslut Twilio eller Telnyx — eller valfri SIP-trunk — importera de telefonnummer du redan äger och låt ThunderPhone-röstagenten besvara och ringa samtal med dem.

Demonummer fungerar bra för prototyper, men produktionstrafik bör använda nummer du äger via din egen VoIP-leverantör. Den här guiden visar det trestegsflöde du följer: testa autentiseringsuppgifter → skapa anslutning → importera nummer → verifiera.

Leverantörer som stöds#

1. Testa autentiseringsuppgifter#

Innan du skapar en sparad VoIP-anslutning testar du leverantörens autentiseringsuppgifter för att bekräfta att de fungerar. Detta returnerar ett verification_evidence_id som du skickar till skapandesteg så att autentiseringsuppgifterna inte debiteras dubbelt för testning.

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

Om någon kontroll misslyckas blir svarets status fail och checks visar vilket steg som misslyckades. Åtgärda konfigurationen hos leverantören (trunktilldelning, IP-tillåtelselista, auktorisering för utgående samtal) och försök igen.

2. Skapa anslutningen#

Skicka verification_evidence_id som du just fick:

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

Svaret är ett VoipConnection-objekt med status="connected". Autentiseringsuppgifter lagras på servern och returneras aldrig i klartext av efterföljande GET-anrop — för att rotera dem kör du en ny test och PATCH:ar med det nya underlaget.

3. Lista och importera nummer#

Granska de nummer som är synliga för dina autentiseringsuppgifter och som inte redan finns i en ThunderPhone-organisation:

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

Importera sedan de nummer du vill ha:

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

Varje import blir en telefonnummerresurs i din organisation med source="voip" och status="provisioning".

4. Verifiera varje importerat nummer#

Importen registrerar numret som tillgängligt; för att faktiskt dirigera samtal via det krävs en verifiering tur och retur (kontroll av inkommande uppringning + auktoriseringskontroll för utgående samtal).

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

Vid lyckad verifiering ändras voip_verification_status till verified och numret får status="active". Vid fel anger svaret vad som misslyckades — åtgärda det (ofta saknas en trunk-tilldelning i leverantörens dashboard) och anropa igen.

5. Tilldela agenter och ta emot ett samtal#

När numret har verifierats tilldelar du agenter för inkommande/utgående samtal på samma sätt som för ett demonummer. Se Hantera inkommande samtal och Ring utgående samtal.

Rotera autentiseringsuppgifter#

När en leverantörsnyckel roteras kör du test-och-uppdatera-flödet igen:

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

Anslutningen ligger kvar — du behöver inte importera numren igen.

Nästa steg#