Tumia nambari zako mwenyewe (VoIP, API)

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.

Watoa huduma wanaotumika#

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.

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

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:

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

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

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

# 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:

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

Kisha ingiza unazotaka:

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

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 na Piga simu zinazotoka.

Kubadilisha vitambulisho#

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

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