---
title: "Подключение собственных номеров (VoIP, API)"
description: "Подключите Twilio, Telnyx, SignalWire, Vonage, Plivo или любой другой SIP-транк через SIP, импортируйте уже принадлежащие вам телефонные номера и позвольте агентам ThunderPhone отвечать на звонки и совершать их с этих номеров."
---

Одобренные номера ThunderPhone могут совершать исходящие вызовы и запускать кампании. Если вы предпочитаете использовать собственные номера через своего VoIP-провайдера, это руководство проведёт вас через процесс подключения: **проверить учётные данные → создать подключение → импортировать номера → подтвердить**.

<Note>
  В панели управления доступна пошаговая версия всего этого процесса в разделе
  **Подключения → VoIP** (`/dashboard/voip-connections`): сначала путь подключения существующего провайдера (Twilio и Telnyx по API-ключу; SignalWire,
  Vonage, Plivo и любые другие транки через ручную SIP-форму с
  шагами для конкретного провайдера и генератором руководства по настройке ИИ), а затем
  пошаговая настройка, открывающая новый аккаунт Telnyx.
</Note>

## Поддерживаемые провайдеры

| Провайдер | ID `provider` | Примечания |
|----------|---------------|-------|
| Twilio | `twilio` | SID аккаунта + токен аутентификации; одно подключение для каждого аккаунта или субаккаунта Twilio (см. [субаккаунты Twilio](#twilio-subaccounts)) |
| Telnyx | `telnyx` | API-ключ; доступна пошаговая настройка (`setup_method: guided_telnyx`) |
| SignalWire | `signalwire` | Нативное подключение провайдера отсутствует; подключите его как `manual` с предустановкой SignalWire SIP |
| Vonage | `vonage` | Нативное подключение провайдера отсутствует; подключите его как `manual` с предустановкой Vonage SIP |
| Ручная настройка SIP | `manual` | Любой SIP-транк, включая SignalWire, Vonage и Plivo. Если начать с одной из плиток этих провайдеров в панели управления, подключение всё равно будет `manual` и сохранит выбор в `sip_config.preset` (`signalwire`, `vonage` или `plivo`) |

## 1. Проверьте учётные данные

Перед созданием сохранённого VoIP-подключения проверьте учётные данные
провайдера, чтобы убедиться, что они работают. В ответе будет возвращён
`verification_evidence_id`, который нужно передать на этапе создания, чтобы
за проверку учётных данных не взималась плата дважды.

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

```json Response
{
  "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`:

```bash
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](/api-reference/voip-connections#connection-object)
со `status="connected"`. Учётные данные хранятся на сервере и никогда
не возвращаются в открытом виде при последующих GET-запросах — чтобы
обновить их, выполните новый `test` и PATCH с новыми подтверждающими данными.

### Субаккаунты Twilio

Подключение Twilio привязано к одной учётной записи Twilio, чьи
Account SID и Auth Token оно содержит. Twilio хранит телефонные номера и SIP-
транки в каждой субучётной записи, поэтому подключение, созданное для родительской
учётной записи, видит только собственные номера родительской записи, а существующее
подключение нельзя позднее переключить на другую субучётную запись.

Чтобы получить доступ к номерам в субаккаунтах, создайте по одному
подключению для каждого субаккаунта. Панель управления делает это за вас:
когда вы подключаете родительский аккаунт с активными субаккаунтами,
диалог настройки выводит их список, вы отмечаете нужные, и ThunderPhone
создаёт подключение (и SIP-транк) в каждом из них. Этот же процесс доступен
через API:

```bash
# 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": "..."}}'
```

```json Response
{
  "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 }
  ]
}
```

```bash
# 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:

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

Затем импортируйте нужные:

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

Каждый импортированный номер становится [ресурсом телефонного номера](/api-reference/phone-numbers)
в вашей организации с `number_type="voip"` и `status="provisioning"`.

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

Импорт регистрирует номер как *доступный*; для фактической маршрутизации
звонков через него требуется проверка. Для подключений через провайдеров (Twilio,
Telnyx) она повторно проверяет учетные данные провайдера и доступность по SIP.
Для подключения **ручной SIP** сначала выполняется тестовый звонок на самого себя по замкнутому маршруту:
ThunderPhone совершает короткий проверочный звонок *с* номера, *через* ваш SIP-
транк, *обратно на тот же номер*. Если это не подтверждает входящий маршрут, система
переходит к короткому проверочному звонку *с* номера, *через* ваш SIP-транк,
*на* номер ThunderPhone. Эти тесты проверяют имя пользователя транка,
пароль, транспорт, исходящую маршрутизацию и доставку входящих вызовов. Ваш оператор
тарифицирует эти звонки как любые другие.

```bash
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. См.
[Обработка входящих звонков](/ru/guides/handle-inbound-calls) и
[Совершение исходящих звонков](/ru/guides/place-outbound-calls).

## Ротация учётных данных

При ротации ключа провайдера повторите процесс проверки и обновления:

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

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

---

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

<CardGroup cols={2}>
  <Card title="Справочник подключений VoIP" icon="phone-volume" href="/api-reference/voip-connections">
    Все поля в ответах о подключении, подтверждении и импорте.
  </Card>
  <Card title="Справочник телефонных номеров" icon="phone" href="/api-reference/phone-numbers">
    Назначайте агентов, переносите номера между организациями, освобождайте номера.
  </Card>
  <Card title="Совершение исходящих звонков" icon="arrow-up-right" href="/ru/guides/place-outbound-calls">
    Теперь, когда номер принадлежит вам, начинайте совершать исходящие звонки.
  </Card>
</CardGroup>