Подключение собственных номеров (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"
  }'

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

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