Developer cookbook

Käytä omia numeroitasi (VoIP, API)

Yhdistä Twilio tai Telnyx — tai mikä tahansa SIP-runko — tuo jo omistamasi puhelinnumerot ja anna ThunderPhone-agenttien vastata niihin ja soittaa niistä puheluita.

Demonumerot sopivat prototyyppien tekemiseen, mutta tuotantoliikenteessä kannattaa käyttää omia numeroitasi oman VoIP-palveluntarjoajasi kautta. Tässä oppaassa käydään läpi kolmivaiheinen työnkulku: testaa tunnistetiedot → luo yhteys → tuo numerot → varmista.

Tuetut palveluntarjoajat#

1. Testaa tunnistetiedot#

Ennen kuin luot pysyvän VoIP-yhteyden, testaa palveluntarjoajan tunnistetiedot varmistaaksesi, että ne toimivat. Tämä palauttaa verification_evidence_id-arvon, jonka välität luontivaiheeseen, jotta tunnistetietoja ei veloiteta testauksesta kahdesti.

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

Jos jokin tarkistus epäonnistuu, vastauksen status on fail ja checks näyttää, mikä vaihe epäonnistui. Korjaa palveluntarjoajan puolen määritys (rungon määritys, IP-sallittujen luettelo, lähtevien puheluiden valtuutus) ja yritä uudelleen.

2. Luo yhteys#

Välitä juuri saamasi 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..."
  }'

Vastaus on VoipConnection-objekti, jonka status="connected". Tunnistetiedot tallennetaan palvelinpuolelle, eikä niitä palauteta selväkielisinä myöhemmissä GET-pyynnöissä — kierrättääksesi ne suorita uusi test ja tee PATCH uudella varmennuksella.

3. Listaa ja tuo numerot#

Tarkista tunnistetiedoillasi näkyvät numerot, jotka eivät vielä ole ThunderPhone-organisaatiossa:

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

Tuo sitten haluamasi numerot:

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

Jokaisesta tuonnista tulee organisaatioosi puhelinnumeron resurssi, jonka source="voip" ja status="provisioning".

4. Vahvista jokainen tuotu numero#

Tuonti rekisteröi numeron saatavilla olevaksi; puhelujen reitittäminen sen kautta edellyttää edestakaista vahvistusta (saapuvan soiton tarkistus + lähtevien puhelujen valtuutustarkistus).

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

Onnistuttaessa voip_verification_status vaihtuu arvoon verified, ja numero siirtyy tilaan status="active". Epäonnistuessa vastaus kertoo, mikä epäonnistui — korjaa se (usein puuttuva trunk-määritys palveluntarjoajan hallintapaneelissa) ja kutsu uudelleen.

5. Määritä agentit ja vastaanota puhelu#

Kun numero on vahvistettu, määrität saapuvien / lähtevien puhelujen agentit samalla tavalla kuin demonumerolle. Katso Saapuvien puhelujen käsittely ja Lähtevien puhelujen soittaminen.

Tunnistetietojen kierrättäminen#

Kun palveluntarjoajan avain vaihtuu, suorita testaa ja päivitä -prosessi uudelleen:

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

Yhteys säilyy ennallaan — numeroita ei tarvitse tuoda uudelleen.

Seuraavat vaiheet#