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

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

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

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

Передумови

Додайте VoIP-номер

Для вихідних дзвінків потрібно володіти from_number через VoIP-підключення. Демо-номери доступні лише для вхідних дзвінків. Див. Використання власних номерів.

Створіть агента

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

Підтримуйте додатний баланс

Вихідні дзвінки повертають 402 Payment Required, якщо баланс ≤ $0.00. Поповніть баланс через POST /v1/billing/top-up або ввімкніть автопоповнення.

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

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

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
  }'

Відповідь:

{ "call_id": 987654321, "status": "initiated" }

status: "initiated" означає лише, що запит прийнято — дзвінок ще не з’єднано. Опитуйте GET /v1/calls/{call_id} для отримання поточного статусу (in_progress → completed / failed).

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

Якщо вам потрібна одноразова підказка, яку не варто зберігати як агента, передайте натомість config. Структура відповідає схемі відповіді вебхука call.incoming:

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 — це найшвидший спосіб дізнатися, що дзвінок завершився. Якщо ви не можете приймати вхідні вебхуки, опитуйте GET /v1/calls/{call_id} кожні кілька секунд; запис містить end_reason, duration_seconds і URL запису після завершення дзвінка.

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

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

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

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

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

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

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

Довідник із вихідних дзвінків

Усі поля запитів і коди помилок.

Отримання call.complete

Передавайте завершені вихідні дзвінки у вашу систему.

Білінг

Автоматично поповнюйте баланс, щоб вихідні дзвінки не завершувалися через нестачу коштів.

Тестування вихідних агентів

Виконайте тестовий запуск свого вихідного агента перед продакшном.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

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

Передумови

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

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

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

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

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

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

Довідник із вихідних дзвінків

Отримання call.complete

Білінг

Тестування вихідних агентів

​Передумови

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

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

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

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

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

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

Довідник із вихідних дзвінків

Отримання call.complete

Білінг

Тестування вихідних агентів

Передумови

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

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

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

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

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

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