Підключайте власні номери (VoIP, API)

Підключіть Twilio, Telnyx, SignalWire, Vonage, Plivo або будь-який інший SIP-транк через SIP, імпортуйте номери телефонів, якими ви вже володієте, і дозвольте агентам 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 покаже, на якому етапі сталася помилка. Виправте конфігурацію на боці провайдера (призначення транка, список дозволених 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 транки в межах кожного субакаунта, тому підключення, створене за допомогою батьківського облікового запису, бачить лише власні номери батьківського облікового запису, а наявне підключення не можна пізніше перемкнути на інший субакаунт.

Щоб отримати доступ до номерів у субакаунтах, створіть по одному підключенню для кожного субакаунта. Панель керування зробить це за вас: коли ви підключаєте батьківський акаунт з активними субакаунтами, у діалоговому вікні налаштування відображається їх список, ви позначаєте потрібні, і 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. Кожне нове підключення потім імпортує та перевіряє номери так само, як підключення, створене вручну. Додайте "enable_transfers": true, щоб також увімкнути переадресацію викликів для SIP-транку кожного нового підключення; збій під час цього буде зазначено в test_result.transfer_enable_error цього підключення та не призведе до збою рядка.

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

Кожен імпорт стає ресурсом телефонного номера у вашій організації з number_type="voip" і status="provisioning".

4. Перевірте кожен імпортований номер#

Імпорт реєструє номер як доступний; фактична маршрутизація викликів через нього потребує верифікації. Для підключень до провайдерів (Twilio, Telnyx) вона повторно перевіряє облікові дані провайдера та доступність SIP. Для підключення ручного SIP спочатку виконується петльовий самовиклик: ThunderPhone здійснює короткий тестовий виклик з номера, через вашу 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". Номер у вашому обліковому записі Telnyx і надалі приймає вхідні дзвінки, якщо його тестовий виклик не вдався або вихідні дзвінки ще не налаштовано: він отримує status="active" зі значенням voip_verification_status unverified, а відповідь пояснює причину. У разі невдачі відповідь детально вказує, що саме не спрацювало — для ручного транку це SIP-відповідь оператора, наприклад «відхилено облікові дані ThunderPhone (SIP 401)» або «не вдалося маршрутизувати дзвінок (SIP 404)» — виправте проблему (облікові дані, дозволені IP-адреси джерела, відсутнє призначення транку в панелі керування провайдера) і повторіть виклик.

Для ручного SIP-підключення зі списком дозволених адрес тест вхідного виклику також не проходить, якщо ці дозволені 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"
  }'

Підключення залишається без змін — повторно імпортувати номери не потрібно.

Наступні кроки#