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

Подключение остаётся на месте — повторно импортировать номера не нужно.

Следующие шаги#