> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Подключите Twilio, Telnyx или любой SIP-транк и импортируйте телефонные номера из существующего аккаунта.

Демонстрационные номера подходят для прототипирования, но для трафика в продакшене
следует использовать номера, принадлежащие вам и предоставленные вашим VoIP-провайдером. В этом руководстве описан
трёхэтапный процесс: **проверить учётные данные → создать
подключение → импортировать номера → подтвердить**.

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

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

| Провайдер  | Идентификатор `provider` | Примечания                                                               |
| ---------- | ------------------------ | ------------------------------------------------------------------------ |
| Twilio     | `twilio`                 | Ключ API + секрет                                                        |
| Telnyx     | `telnyx`                 | Ключ API; доступно пошаговое подключение (`setup_method: guided_telnyx`) |
| SignalWire | `signalwire`             | **Скоро появится** — пока подключайтесь через ручной SIP                 |
| Vonage     | `vonage`                 | **Скоро появится** — пока подключайтесь через ручной SIP                 |
| Ручной SIP | `manual`                 | Любой SIP-транк — используйте собственную конфигурацию                   |

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

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

```bash theme={null}
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 theme={null}
{
  "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 theme={null}
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 с новыми данными подтверждения.

## 3. Просмотрите и импортируйте номера

Просмотрите номера, доступные вашим учётным данным, которые ещё не добавлены
в организацию ThunderPhone:

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

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

```bash theme={null}
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)
в вашей организации со `source="voip"` и `status="provisioning"`.

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

Импорт регистрирует номер как *доступный*; для фактической маршрутизации звонков
через него требуется двусторонняя проверка (проверка входящего набора +
проверка авторизации исходящих звонков).

```bash theme={null}
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. Назначьте агентов и примите звонок

После проверки номера назначьте агентов для входящих / исходящих звонков
так же, как для демонстрационного номера. См.
[Обработка входящих звонков](/ru/guides/handle-inbound-calls) и
[Совершение исходящих звонков](/ru/guides/place-outbound-calls).

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

При ротации ключа провайдера повторите процесс «проверка, затем обновление»:

```bash theme={null}
# 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>