Използвайте собствени номера (VoIP, API)

Свържете Twilio или Telnyx — или който и да е SIP trunk — импортирайте телефонните номера, които вече притежавате, и позволете на агентите на ThunderPhone да отговарят и да извършват обаждания с тях.

Номерата на ThunderPhone покриват входящите обаждания, но за изходящи обаждания и кампании са нужни номера, които притежавате чрез вашия VoIP доставчик. Това ръководство ви превежда през процеса в четири стъпки: тестване на идентификационните данни → създаване на връзка → импортиране на номера → потвърждаване.

Поддържани доставчици#

1. Тествайте идентификационните данни#

Преди да създадете постоянна VoIP връзка, проверете идентификационните данни на доставчика, за да потвърдите, че работят. Това връща verification_evidence_id, който подавате към стъпката за създаване, така че идентификационните данни да не бъдат таксувани двойно за тестване.

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

Ако някоя проверка е неуспешна, status в отговора ще бъде fail, а checks ще покаже на коя стъпка е възникнал проблем. Коригирайте конфигурацията от страна на доставчика (назначаване на trunk, списък с разрешени IP адреси, разрешение за изходящи обаждания) и опитайте отново.

2. Създайте връзката#

Подайте 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..."
  }'

Отговорът е обект VoipConnection с status="connected". Идентификационните данни се съхраняват от страна на сървъра и никога не се връщат като обикновен текст при последващи GET заявки — за да ги смените, изпълнете нов test и PATCH заявка с новите доказателства.

Подакаунти на Twilio#

Връзката с Twilio е обвързана с единствения Twilio акаунт, чиито Account SID и Auth Token съдържа. Twilio съхранява телефонните номера и SIP транковете във всеки подакаунт, така че връзка, създадена с родителския акаунт, вижда само собствените номера на родителския акаунт, а съществуваща връзка не може по-късно да бъде превключена към друг подакаунт (актуализацията се отхвърля, защото SIP транкът на връзката се намира в първоначалния акаунт).

За да получите достъп до номерата, съхранявани в подакаунти, създайте по една връзка за всеки подакаунт. Таблото за управление прави това вместо вас: когато свържете родителски акаунт с активни подакаунти, диалоговият прозорец за настройка ги изброява, вие отбелязвате желаните и ThunderPhone създава връзка (и SIP транк) във всеки от тях. Същият поток е наличен и чрез 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..."]}'

Отговорът съдържа по един ред за всеки подакаунт със status created, skipped (вече свързан) или failed, както и error, по която можете да предприемете действие. Редовете са независими, така че грешка в един подакаунт никога не блокира останалите, а discovery_id остава валиден 30 минути, така че неуспешен ред може просто да бъде опитан отново. Токените на подакаунтите се прочитат от Twilio при откриването и се съхраняват в новата връзка; те никога не се връщат от API. След това всяка нова връзка импортира и проверява номерата точно както връзка, създадена ръчно.

3. Избройте и импортирайте номера#

Проверете номерата, видими за вашите идентификационни данни, които все още не са в организация на ThunderPhone:

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

След това импортирайте желаните:

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

Всеки импорт се превръща в ресурс за телефонен номер във вашата организация с source="voip" и status="provisioning".

4. Проверете всеки импортиран номер#

Импортирането регистрира номера като наличен; за действителното пренасочване на обаждания през него е нужна проверка. При връзки с доставчици (Twilio, Telnyx) това проверява отново идентификационните данни на доставчика и SIP достъпността. При ръчна SIP връзка се извършва кратко тестово обаждане (няколко секунди, прекъснато автоматично) от номера, през вашия SIP транк, към номер на ThunderPhone — така потребителското име, паролата, транспортът и изходящото маршрутизиране на транка се проверяват реално. Вашият телекомуникационен доставчик таксува това обаждане като всяко друго.

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

При успех voip_verification_status се променя на verified, а номерът получава status="active". При неуспех отговорът посочва какво не е наред — за ръчен транк това е SIP отговорът на доставчика, например „отхвърли идентификационните данни на ThunderPhone (SIP 401)“ или „не можа да маршрутизира обаждане (SIP 404)“ — коригирайте го (идентификационни данни, разрешени IP адреси на източника, липсващо присвояване на транк в таблото на доставчика) и извикайте отново.

5. Присвоете агенти и приемете обаждане#

След като номерът е проверен, присвоявате агенти за входящи/изходящи обаждания по същия начин като при номер на ThunderPhone. Вижте Обработване на входящи обаждания и Извършване на изходящи обаждания.

Подновяване на идентификационни данни#

Когато ключът на доставчик бъде подновен, изпълнете отново последователността тест и актуализация:

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

Връзката остава на място — няма нужда да импортирате отново номерата.

Следващи стъпки#