Developer cookbook

Використовуйте власні номери (VoIP, API)

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

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. Перевірте кожен імпортований номер#

Імпорт реєструє номер як доступний; для фактичної маршрутизації викликів через нього потрібна перевірка в обидва боки (перевірка вхідного набору + перевірка авторизації вихідних викликів).

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". У разі помилки відповідь вказує, що саме не вдалося — виправте проблему (часто це відсутнє призначення транку в панелі керування провайдера) і повторіть виклик.

5. Призначте агентів і здійсніть виклик#

Після перевірки номера призначайте агентів для вхідних / вихідних викликів так само, як для демо-номера. Дивіться Обробка вхідних викликів і Здійснення вихідних викликів.

Ротація облікових даних#

Коли ключ провайдера змінюється, повторно виконайте процес перевірки й оновлення:

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

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

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