> ## 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 із генератором
  посібника з налаштування AI.
</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. Призначте агентів і прийміть дзвінок

Після перевірки номера призначайте агентів для вхідних / вихідних дзвінків
так само, як для демонстраційного номера. Див.
[Обробка вхідних дзвінків](/uk/guides/handle-inbound-calls) і
[Здійснення вихідних дзвінків](/uk/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="/uk/guides/place-outbound-calls">
    Тепер, коли номер належить вам, починайте здійснювати вихідні дзвінки.
  </Card>
</CardGroup>