---
title: "Käytä omia numeroitasi (VoIP, API)"
description: "Yhdistä Twilio, Telnyx, SignalWire, Vonage, Plivo tai mikä tahansa muu SIP-runko SIP:n kautta, tuo jo omistamasi puhelinnumerot ja anna ThunderPhone-agenttien vastata niihin ja soittaa niistä puheluita."
---

Hyväksytyillä ThunderPhone-numeroilla voi soittaa lähteviä puheluita ja suorittaa kampanjoita. Jos haluat käyttää omistamiasi numeroita oman VoIP-palveluntarjoajasi kautta, tässä oppaassa käydään läpi yhteyden muodostaminen: **testaa tunnistetiedot → luo yhteys → tuo numerot → vahvista**.

<Note>
  Hallintapaneelissa on ohjattu versio tästä koko työnkulusta kohdassa
  **Yhteydet → VoIP** (`/dashboard/voip-connections`): ensin olemassa olevan
  yhteyden muodostamisen polku (Twilio ja Telnyx API-avaimella; SignalWire,
  Vonage, Plivo ja mikä tahansa muu trunk manuaalisella SIP-lomakkeella,
  palveluntarjoajakohtaisilla vaiheilla ja tekoälyn asennusopasgeneraattorilla)
  ja toisena ohjattu käyttöönotto, joka avaa uuden Telnyx-tilin.
</Note>

## Tuetut palveluntarjoajat

| Palveluntarjoaja | `provider`-tunnus | Huomautukset |
|----------|---------------|-------|
| Twilio | `twilio` | Account SID + Auth Token; yksi yhteys Twilio-tiliä tai -alatiliä kohden (katso [Twilion alatilit](#twilio-subaccounts)) |
| Telnyx | `telnyx` | API-avain; ohjattu käyttöönotto saatavilla (`setup_method: guided_telnyx`) |
| SignalWire | `signalwire` | Ei natiivia palveluntarjoajayhteyttä; yhdistä se `manual`-asetuksella SignalWire SIP -esiasetuksella |
| Vonage | `vonage` | Ei natiivia palveluntarjoajayhteyttä; yhdistä se `manual`-asetuksella Vonage SIP -esiasetuksella |
| Manuaalinen SIP | `manual` | Mikä tahansa SIP-runko, mukaan lukien SignalWire, Vonage ja Plivo. Jos aloitat jostakin näistä palveluntarjoajan laatoista hallintapaneelissa, yhteys on silti `manual` ja tallentaa valinnan kohtaan `sip_config.preset` (`signalwire`, `vonage` tai `plivo`) |

## 1. Testaa tunnistetiedot

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

```bash
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" }
  }'
```

```json Response
{
  "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ääritykset
(trunkin määritys, IP-sallittujen luettelo, lähtevien puheluiden valtuutus)
ja yritä uudelleen.

## 2. Luo yhteys

Välitä juuri saamasi `verification_evidence_id`:

```bash
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](/api-reference/voip-connections#connection-object),
jonka `status="connected"`. Tunnistetiedot ja muut salaiset yhteysarvot tallennetaan palvelinpuolelle, eikä niitä koskaan
palauteta selväkielisinä myöhemmissä GET-pyynnöissä — kierrätä ne suorittamalla uusi
`test` ja PATCH uudella todistusaineistolla.

### Twilio-alitilit

Twilio-yhteys on sidottu siihen yksittäiseen Twilio-tiliin, jonka
Account SID- ja Auth Token -tiedot sillä ovat. Twilio säilyttää puhelinnumerot ja SIP-
rungot kunkin alatilin sisällä, joten päätilillä muodostettu yhteys näkee vain
päätilin omat numerot, eikä olemassa olevaa yhteyttä voi myöhemmin vaihtaa toiseen alatilin.

Jos haluat käyttää alitileillä olevia numeroita, luo yksi yhteys jokaista alitiliä
kohden. Hallintapaneeli tekee tämän puolestasi: kun yhdistät päätilin, jolla on
aktiivisia alatilejä, asetusikkuna luettelee ne, valitset haluamasi, ja ThunderPhone
luo yhteyden (ja SIP-rungon) kuhunkin niistä. Sama työnkulku on käytettävissä API:n kautta:

```bash
# 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": "..."}}'
```

```json Response
{
  "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 }
  ]
}
```

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

Vastaus sisältää yhden rivin kutakin alatiliä kohti, ja sen `status` on
`created`, `skipped` (jo yhdistetty) tai `failed` sekä `error`,
jonka perusteella voit toimia. Rivit ovat toisistaan riippumattomia, joten yhden alatilin
epäonnistuminen ei koskaan estä muita, ja `discovery_id` on voimassa 30
minuuttia, joten epäonnistunutta riviä voi yrittää uudelleen. Alatilitunnukset
luetaan Twiliosta etsinnän aikana ja tallennetaan uuteen yhteyteen;
niitä ei koskaan palauteta API:n kautta. Jokainen uusi yhteys tuo sitten
numerot ja vahvistaa ne aivan kuten käsin luomasi yhteys.
Lisää `"enable_transfers": true`, jotta myös puhelunsiirrot otetaan käyttöön kunkin
uuden yhteyden SIP-rungossa; kyseinen epäonnistuminen raportoidaan
yhteyden `test_result.transfer_enable_error`-kentässä eikä se epäonnistuta
riviä.

## 3. Luettele ja tuo numerot

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

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

Tuo sitten haluamasi numerot:

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

Jokainen tuonti luo organisaatioosi [puhelinnumeron resurssin](/api-reference/phone-numbers),
jonka `number_type="voip"` ja `status="provisioning"`.

## 4. Vahvista jokainen tuotu numero

Tuonti rekisteröi numeron *saatavilla olevaksi*; puheluiden todellinen reitittäminen
sen kautta edellyttää vahvistusta. Palveluntarjoajayhteyksissä (Twilio,
Telnyx) tämä tarkistaa palveluntarjoajan tunnistetiedot ja SIP-saavutettavuuden uudelleen.
**manuaalisessa SIP**-yhteydessä järjestelmä yrittää ensin silmukoidun itsekutsun:
ThunderPhone soittaa lyhyen testipuhelun *numerosta*, *SIP-runkosi kautta*
*takaisin samaan numeroon*. Jos tämä ei vahvista saapuvaa reittiä, se
käyttää varamenetelmänä lyhyttä testipuhelua *numerosta*, *SIP-runkosi kautta*
*ThunderPhone-numeroon*. Nämä testit tarkistavat rungon käyttäjänimen,
salasanan, siirtoprotokollan, lähtevän reitityksen ja saapuvien puheluiden toimituksen. Operaattorisi
laskuttaa nämä puhelut kuten mitkä tahansa muutkin.

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

Onnistuessaan `voip_verification_status` vaihtuu arvoon `verified`, ja
numero siirtyy tilaan `status="active"`. Omalla Telnyx-tililläsi oleva numero
vastaanottaa edelleen saapuvia puheluita, vaikka sen testipuhelu epäonnistuu tai
lähteviä puheluita ei ole vielä määritetty: se siirtyy tilaan `status="active"`,
jolloin `voip_verification_status`-arvoksi asetetaan `unverified`, ja vastaus
kertoo syyn. Epäonnistuessaan vastaus ilmoittaa
mikä epäonnistui — manuaalisen trunkin tapauksessa kyse on operaattorin SIP-vastauksesta,
esimerkiksi *"ThunderPhonen tunnistetiedot hylättiin (SIP 401)"* tai *"puhelua ei
voitu reitittää (SIP 404)"* — korjaa ongelma (tunnistetiedot, sallitut lähde-IP-osoitteet,
puuttuva trunk-määritys palveluntarjoajan hallintapaneelissa) ja soita uudelleen.

Sallittujen luetteloon perustuvassa manuaalisessa SIP-yhteydessä saapuvien puheluiden testi epäonnistuu myös, jos
nämä sallitut lähde-IP-osoitteet estäisivät todellisen saapuvan puhelun.

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

Kun numero on vahvistettu, määrität saapuvien / lähtevien puhelujen
agentit samalla tavalla kuin ThunderPhone-numerolle. Katso
[Saapuvien puhelujen käsittely](/fi/guides/handle-inbound-calls) ja
[Lähtevien puhelujen soittaminen](/fi/guides/place-outbound-calls).

## Tunnistetietojen vaihtaminen

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

```bash
# 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

<CardGroup cols={2}>
  <Card title="VoIP-yhteyksien viite" icon="phone-volume" href="/api-reference/voip-connections">
    Kaikki yhteys-, todiste- ja tuontivastausten kentät.
  </Card>
  <Card title="Puhelinnumeroiden viite" icon="phone" href="/api-reference/phone-numbers">
    Määritä agentteja, siirrä organisaatioiden välillä ja vapauta numeroita.
  </Card>
  <Card title="Lähtevien puhelujen soittaminen" icon="arrow-up-right" href="/fi/guides/place-outbound-calls">
    Nyt kun omistat numeron, aloita lähtevien puhelujen soittaminen.
  </Card>
</CardGroup>