> ## 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.

# Здійснюйте вихідні дзвінки (API)

> Ініціюйте вихідний дзвінок за допомогою ШІ зі свого коду — для опитувань, подальших звернень або підтверджень.

Вихідні дзвінки дають змогу передати ThunderPhone номер призначення та
конфігурацію агента, щоб ШІ здійснив дзвінок від вашого імені. Типові сценарії
використання:

* Підтвердження записів
* Зворотні дзвінки для опитувань
* Повторні звернення після пропущеного дзвінка
* Сповіщення для диспетчеризації

<Note>
  Потрібно обдзвонити цілий список? Функція
  [**Кампанії**](/uk/guides/outbound-campaigns) на панелі керування
  (`/dashboard/campaigns`) приймає CSV-файл контактів і самостійно обробляє
  вікна дзвінків з урахуванням часових поясів, паралельність і політику
  повторних спроб. У цьому посібнику розглянуто окремі програмні дзвінки.
</Note>

## Передумови

<Steps>
  <Step title="Додайте VoIP-номер">
    Для вихідних дзвінків потрібно володіти `from_number` через
    [VoIP-підключення](/api-reference/voip-connections). Демо-номери доступні
    лише для вхідних дзвінків. Див.
    [Використання власних номерів](/uk/guides/bring-your-own-numbers).
  </Step>

  <Step title="Створіть агента">
    Підказка для вихідних дзвінків зазвичай починається з того, що агент
    представляється й пояснює мету дзвінка — «Вітаю, це Acme телефонує, щоб
    підтвердити ваш запис на завтра о 15:00…». Встановіть
    `outbound_speak_order` на `agent_first` (значення за замовчуванням).
  </Step>

  <Step title="Підтримуйте додатний баланс">
    Вихідні дзвінки повертають `402 Payment Required`, якщо баланс ≤
    `$0.00`. Поповніть баланс через
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    або ввімкніть [автопоповнення](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Здійсніть дзвінок зі збереженим агентом

Найпростіший спосіб — вказати агента за id:

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'
```

Відповідь:

```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"` означає лише, що запит прийнято — дзвінок
  **ще не з’єднано**. Опитуйте
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  для отримання поточного статусу (`in_progress` → `completed` / `failed`).
</Warning>

## Здійсніть дзвінок із вбудованою конфігурацією

Якщо вам потрібна одноразова підказка, яку не варто зберігати як агента,
передайте натомість `config`. Структура відповідає схемі відповіді
[вебхука `call.incoming`](/uk/webhooks/call-incoming):

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## Відстежуйте дзвінок

Паралельно підпишіться на
[вебхук `telephony.complete`](/uk/webhooks/events) —
це найшвидший спосіб дізнатися, що дзвінок завершився. Якщо ви не можете
приймати вхідні вебхуки, опитуйте `GET /v1/calls/{call_id}` кожні кілька
секунд; запис містить `end_reason`, `duration_seconds` і URL запису після
завершення дзвінка.

## Важливі режими помилок

| Помилка                                                  | Виправлення                                                                                                      |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | Поповніть баланс або ввімкніть автопоповнення                                                                    |
| `403` вихідні дзвінки заблоковано (демо-номер)           | Натомість додайте VoIP-номер                                                                                     |
| `403` вихідні дзвінки заблоковано (непідтверджений VoIP) | Виконайте [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | Переконайтеся, що `from_number` відповідає номеру телефону, яким ви володієте                                    |
| `502 Bad Gateway`                                        | Тимчасова помилка SIP / LiveKit; повторна спроба безпечна                                                        |

## Керування часом утримання

Тривалі вихідні дзвінки, коли абонент повільно відповідає
(IVR-меню, черги), можна обмежити за допомогою `max_hold_seconds`:

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

Агент завершує дзвінок, якщо протягом останніх
N секунд не отримано аудіо від людини. За замовчуванням — 900 (15 хвилин).

***

## Наступні кроки

<CardGroup cols={2}>
  <Card title="Довідник із вихідних дзвінків" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Усі поля запитів і коди помилок.
  </Card>

  <Card title="Отримання call.complete" icon="bolt" href="/uk/webhooks/call-complete">
    Передавайте завершені вихідні дзвінки у вашу систему.
  </Card>

  <Card title="Білінг" icon="credit-card" href="/api-reference/billing">
    Автоматично поповнюйте баланс, щоб вихідні дзвінки не завершувалися через нестачу коштів.
  </Card>

  <Card title="Тестування вихідних агентів" icon="flask" href="/uk/guides/test-agents">
    Виконайте тестовий запуск свого вихідного агента перед продакшном.
  </Card>
</CardGroup>