---
title: "Tumia nambari zako mwenyewe (VoIP, API)"
description: "Unganisha Twilio au Telnyx — au SIP trunk yoyote — leta nambari za simu ambazo tayari unamiliki, na uwaruhusu ejenti wa ThunderPhone kujibu na kupiga simu kupitia nambari hizo."
---

Namba za ThunderPhone hushughulikia simu zinazoingia, lakini simu zinazotoka na
kampeni zinahitaji namba unazomiliki kupitia mtoa huduma wako wa VoIP. Mwongozo huu unakuongoza
katika mtiririko wa hatua tatu: **jaribu vitambulisho → unda
muunganisho → leta namba → thibitisha**.

<Note>
  Dashibodi ina toleo elekezi la mtiririko huu wote chini ya
  **Miunganisho → VoIP** (`/dashboard/voip-connections`): usanidi elekezi wa Telnyx
  unaokuongoza katika uundaji wa akaunti na funguo za API, njia ya
  kuunganisha akaunti iliyopo, na fomu ya SIP ya mwongozo yenye jenereta ya
  mwongozo wa usanidi wa AI.
</Note>

## Watoa huduma wanaotumika

| Mtoa huduma | kitambulisho cha `provider` | Maelezo |
|----------|---------------|-------|
| Twilio | `twilio` | SID ya Akaunti + Tokeni ya Uthibitishaji; muunganisho mmoja kwa kila akaunti au akaunti ndogo ya Twilio (tazama [akaunti ndogo za Twilio](#twilio-subaccounts)) |
| Telnyx | `telnyx` | Ufunguo wa API; uanzishaji elekezi unapatikana (`setup_method: guided_telnyx`) |
| SignalWire | `signalwire` | **Inakuja hivi karibuni** — unganisha kupitia SIP ya Mwongozo leo |
| Vonage | `vonage` | **Inakuja hivi karibuni** — unganisha kupitia SIP ya Mwongozo leo |
| SIP ya Mwongozo | `manual` | Tranki yoyote ya SIP — leta usanidi wako mwenyewe |

## 1. Jaribu vitambulisho

Kabla ya kuunda muunganisho wa VoIP uliohifadhiwa, jaribu vitambulisho vya
mtoa huduma ili kuthibitisha kuwa vinafanya kazi. Hii hurejesha
`verification_evidence_id` unayopitisha kwenye hatua ya kuunda ili
vitambulisho visitozwe mara mbili kwa ajili ya majaribio.

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

Ukaguzi wowote ukishindwa, `status` ya jibu itakuwa `fail` na `checks` itaonyesha
ni hatua gani imeshindwa. Rekebisha usanidi wa upande wa mtoa huduma (ugawaji wa
tranki, orodha ya kuruhusu IP, uidhinishaji wa simu zinazotoka) kisha ujaribu tena.

## 2. Unda muunganisho

Pitisha `verification_evidence_id` uliyopata hivi punde:

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

Jibu ni [kitu cha VoipConnection](/api-reference/voip-connections#connection-object)
chenye `status="connected"`. Vitambulisho huhifadhiwa upande wa seva na kamwe
havirejeshwi kama maandishi wazi na GET zinazofuata — ili kuvizungusha, endesha
`test` mpya na PATCH yenye ushahidi mpya.

### Akaunti ndogo za Twilio

Muunganisho wa Twilio hufungamana na akaunti moja ya Twilio ambayo ina
Account SID na Auth Token zake. Twilio huhifadhi namba za simu na SIP
trunks ndani ya kila akaunti ndogo, kwa hivyo muunganisho ulioundwa kwa
akaunti kuu huona tu namba za akaunti kuu yenyewe, na muunganisho uliopo
hauwezi kubadilishwa baadaye kwenda akaunti ndogo tofauti (usasishaji
hukatalika kwa sababu SIP trunk ya muunganisho iko katika akaunti ya
awali).

Ili kufikia namba zilizo katika akaunti ndogo, unda muunganisho mmoja kwa kila
akaunti ndogo. Dashibodi hukufanyia hili: unapounganisha akaunti kuu yenye
akaunti ndogo zinazotumika, kidirisha cha usanidi huziorodhesha, unaweka tiki
kwenye zile unazotaka, na ThunderPhone huunda muunganisho (na SIP trunk)
katika kila moja. Mtiririko huohuo unapatikana kupitia API:

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

Jibu lina safu moja kwa kila akaunti ndogo yenye `status` ya
`created`, `skipped` (tayari imeunganishwa) au `failed` pamoja na `error`
unayoweza kufanyia kazi. Safu zinajitegemea, kwa hivyo hitilafu katika akaunti
ndogo moja haiwazuii nyingine, na `discovery_id` hubaki halali kwa dakika 30
ili safu iliyoshindikana iweze kujaribiwa tena kwa urahisi. Tokeni za akaunti
ndogo husomwa kutoka Twilio wakati wa ugunduzi na kuhifadhiwa kwenye muunganisho
mpya; hazirejeshwi kamwe na API. Kisha kila muunganisho mpya huingiza na
kuthibitisha namba sawasawa na muunganisho uliounda mwenyewe.

## 3. Orodhesha na ingiza namba

Kagua namba zinazoonekana kwa vitambulisho vyako ambazo bado haziko
katika org ya ThunderPhone:

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

Kisha ingiza unazotaka:

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

Kila uingizaji huwa [rasilimali ya namba ya simu](/api-reference/phone-numbers)
katika org yako yenye `source="voip"` na `status="provisioning"`.

## 4. Thibitisha kila nambari iliyoingizwa

Kuagiza husajili nambari kama *inayopatikana*; kuelekeza simu
kupitia nambari hiyo kunahitaji uthibitishaji. Kwa miunganisho ya watoa huduma (Twilio,
Telnyx), hilo hukagua tena vitambulisho vya mtoa huduma na ufikiwaji wa SIP.
Kwa muunganisho wa **SIP wa mkono** huweka simu fupi ya majaribio (sekunde chache,
hukatwa kiotomatiki) *kutoka* kwenye nambari, *kupitia* mkonga wako wa SIP,
*kwenda* kwenye nambari ya ThunderPhone — hivyo jina la mtumiaji, nenosiri,
usafirishaji na uelekezaji wa kutoka wa mkonga huthibitishwa kiuhalisia. Mtoa huduma wako
hutoza simu hiyo kama simu nyingine yoyote.

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

Ikifanikiwa, `voip_verification_status` hubadilika kuwa `verified` na
nambari huingia kwenye `status="active"`. Ikishindikana, jibu hueleza wazi
kilichoshindikana — kwa mkonga wa mkono hilo ni jibu la SIP la mtoa huduma, kwa
mfano *"ilikataa vitambulisho vya ThunderPhone (SIP 401)"* au *"haikuweza
kuelekeza simu (SIP 404)"* — rekebisha tatizo (vitambulisho, IP za chanzo
zinazoruhusiwa, uwekaji wa mkonga unaokosekana kwenye dashibodi ya mtoa huduma) kisha
piga simu tena.

## 5. Wape ejenti na pokea simu

Nambari ikishathibitishwa, unawapa ejenti wa simu zinazoingia / zinazotoka
kwa njia sawa na nambari ya ThunderPhone. Tazama
[Shughulikia simu zinazoingia](/sw/guides/handle-inbound-calls) na
[Piga simu zinazotoka](/sw/guides/place-outbound-calls).

## Kubadilisha vitambulisho

Ufunguo wa mtoa huduma unapobadilishwa, endesha tena mtiririko wa kujaribu kisha kusasisha:

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

Muunganisho hubaki mahali pake — hakuna haja ya kuagiza nambari tena.

---

## Hatua zinazofuata

<CardGroup cols={2}>
  <Card title="Marejeleo ya miunganisho ya VoIP" icon="phone-volume" href="/api-reference/voip-connections">
    Kila sehemu kwenye majibu ya muunganisho, ushahidi na uagizaji.
  </Card>
  <Card title="Marejeleo ya nambari za simu" icon="phone" href="/api-reference/phone-numbers">
    Wape ejenti, hamisha kati ya mashirika, achilia nambari.
  </Card>
  <Card title="Piga simu zinazotoka" icon="arrow-up-right" href="/sw/guides/place-outbound-calls">
    Kwa kuwa sasa unamiliki nambari, anza kupiga simu zinazotoka.
  </Card>
</CardGroup>