Developer cookbook

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

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

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

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

Передумови#

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

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

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

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

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

   Вихідні дзвінки повертають 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" }

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

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

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

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

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

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

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

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