---
title: "Здійснюйте вихідні дзвінки (API)"
description: "Ініціюйте вихідний дзвінок за допомогою ШІ зі свого коду — для опитувань, повторних звернень або підтверджень."
---
Вихідні дзвінки дають змогу передати ThunderPhone номер призначення та
конфігурацію агента, щоб ШІ здійснив дзвінок від вашого імені. Типові випадки використання:
- Підтвердження записів
- Повторні дзвінки для опитувань
- Повторні звернення після пропущеного дзвінка
- Сповіщення у стилі диспетчеризації
Потрібно обдзвонити цілий список? Функція
[**Кампанії**](/uk/guides/outbound-campaigns) на інформаційній панелі
(`/dashboard/campaigns`) приймає CSV із контактами та самостійно обробляє
вікна дзвінків з урахуванням часових поясів, паралельність і політику
повторних спроб. У цьому посібнику описано окремі програмні дзвінки.
## Передумови
Використовуйте номер, яким ви володієте через
[VoIP-підключення](/api-reference/voip-connections), або надішліть запит на дозвіл
використовувати свої номери ThunderPhone для вихідних дзвінків на сторінці Phone Numbers.
Номери ThunderPhone спочатку доступні лише для вхідних дзвінків. ThunderPhone розглядає кожен
запит вручну; після схвалення ці номери можуть здійснювати дзвінки в межах
схваленого денного ліміту (який скидається о 00:00 UTC) і запускати кампанії, а ви
можете подати запит на вищий ліміт. Клієнтські VoIP-номери не мають денного ліміту, тому ми рекомендуємо
їх для вихідних дзвінків. Див.
[Використання власних номерів](/uk/guides/bring-your-own-numbers).
Промпт для вихідних дзвінків зазвичай починається з того, що агент
представляється та пояснює мету дзвінка — «Вітаю, це Acme телефонує, щоб
підтвердити ваш запис на завтра о 15:00…». Установіть
`outbound_speak_order` у значення `agent_first` (за замовчуванням).
Вихідні дзвінки повертають `402 Payment Required`, якщо баланс ≤
`$0.00`. Поповніть баланс або ввімкніть автоматичне поповнення в розділі
**Organization → Billing Settings** на панелі керування. Ваш ключ `sk_live_`
може перевіряти баланс за допомогою
[`GET /v1/billing`](/api-reference/billing#get-billing-account), але
не може поповнювати баланс або змінювати автоматичне поповнення.
## Здійснення дзвінка зі збереженим агентом
Найпростіший спосіб — указати агента за ідентифікатором:
```bash
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": "+14155552671",
"agent_id": 12
}'
```
Відповідь:
```json
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` означає лише, що запит прийнято — дзвінок
**ще не підключено**. Надсилайте запити до
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
для отримання поточного статусу (`in_progress` → `completed` / `failed`).
## Здійснення дзвінка з вбудованою конфігурацією
Якщо вам потрібен одноразовий промпт, який не варто зберігати як агента,
передайте натомість `config`. Структура відповідає схемі відповіді
[вебхука `call.incoming`](/uk/webhooks/call-incoming):
```bash
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": "+14155552671",
"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 запису
після завершення дзвінка.
Якщо ваш агент налаштований на вилучення структурованих даних після дзвінка,
ці дані доставляються окремо після завершення фіналізації.
### Передавання змінних для дзвінка збереженому агенту
Збережені агенти можуть використовувати в тексті промпту заповнювачі на кшталт `{{name}}` або `{{name|there}}`.
Коли ви здійснюєте вихідний дзвінок із `agent_id`, передайте
`variables` зі значеннями для цього дзвінка:
```json
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}
```
Використовуйте рядкові значення з ключами, що відповідають назві заповнювача. Ці змінні застосовуються до
збережених агентів; у вбудованому прикладі `config` у цьому посібнику вони не використовуються.
## Важливі сценарії помилок
| Помилка | Виправлення |
|-------|-----|
| `402 Payment Required` | Поповніть баланс або ввімкніть автоматичне поповнення |
| `400` із `code: destination_not_allowed` | ThunderPhone не телефонує на цей номер: недійсні номери, екстрені номери, номери з підвищеною тарифікацією, короткі номери або номери в країнах під санкціями. Із номерів ThunderPhone доступні лише звичайні номери США та Канади (без номерів із підвищеною тарифікацією). `reason` указує причину; див. [заблоковані напрямки](/api-reference/outbound-calls#blocked-destinations) |
| `409` із `retryable: false` для номера ThunderPhone | Дотримуйтеся значення `code`: подайте запит на вихідні дзвінки на сторінці номерів телефону, зачекайте на розгляд або використайте інший придатний номер |
| `429` із `code: platform_outbound_daily_limit_reached` | Організація використала сьогоднішній ліміт вихідних дзвінків із номерів ThunderPhone. Зачекайте до `resets_at` (00:00 UTC), подайте запит на вищий ліміт на сторінці номерів телефону або телефонуйте з номера через власне VoIP-підключення |
| `429` із `code: concurrent_call_limit_reached` | В організації стільки ж активних дзвінків, скільки становить її [ліміт одночасних дзвінків](/api-reference/introduction#call-limits) (за замовчуванням 20, з урахуванням вхідних, вихідних, веб- і тестових дзвінків). Повторіть спробу після кількості секунд із заголовка `Retry-After` або після завершення дзвінка; напишіть на support@thunderphone.com, щоб підвищити ліміт |
| `429` із `code: same_number_too_soon` | Ви телефонували на той самий `to_number` менш ніж 10 секунд тому. Повторіть спробу після кількості секунд із заголовка `Retry-After` |
| `409` із `retryable: false` для клієнтського VoIP-номера | Виправте стан, указаний у `code`; у разі помилки верифікації виконайте [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| Конфлікт ідемпотентності `409` | Повторно використовуйте ключ лише з оригінальним нормалізованим запитом або надішліть новий ключ |
| `404 from_number is not registered to this organization` | Переконайтеся, що `from_number` відповідає активному номеру телефону у вашій організації. Номер, який уже налаштовується, завершився помилкою, вивільняється або вивільнений, також повертає цю відповідь |
| `500` лише з полем `detail` | Не налаштовано вихідний транк. Зверніться до служби підтримки; це не проблема стану номера, яку ви можете виправити |
| `502 Bad Gateway` | Тимчасова помилка SIP / LiveKit; повторна спроба безпечна |
Перегляньте [довідник вихідних дзвінків](/api-reference/outbound-calls#error-responses),
щоб отримати повний стабільний список кодів відповідності вимогам і обидві форми відповіді `409`.
Якщо активний номер стає невідповідним вимогам після прийняття запиту, але до
здійснення дзвінка, остаточна перевірка повертає корисне навантаження `409`, яке не можна повторити.
## Керування часом очікування
Вихідні дзвінки, які тривають довго через повільну відповідь абонента
(IVR-дерева, черги), можна обмежити за допомогою `max_hold_seconds`:
```json
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}
```
Агент завершує дзвінок, якщо протягом останніх
N секунд не було отримано аудіо від людини. За замовчуванням — 900 секунд (15 хвилин).
---
## Наступні кроки
Усі поля запиту та коди помилок.
Передавайте завершені вихідні дзвінки до вашої системи.
Увімкніть автопоповнення, щоб вихідні дзвінки ніколи не завершувалися через нестачу балансу.
Виконайте пробний запуск вашого вихідного агента перед продакшном.