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

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

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

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

Передумови#

1. Виберіть номер із підтримкою вихідних дзвінків

   Використовуйте номер, яким ви володієте через VoIP-підключення, або надішліть запит на дозвіл використовувати свої номери ThunderPhone для вихідних дзвінків на сторінці Phone Numbers. Номери ThunderPhone спочатку доступні лише для вхідних дзвінків. ThunderPhone розглядає кожен запит вручну; після схвалення ці номери можуть здійснювати дзвінки в межах схваленого денного ліміту (який скидається о 00:00 UTC) і запускати кампанії, а ви можете подати запит на вищий ліміт. Клієнтські VoIP-номери не мають денного ліміту, тому ми рекомендуємо їх для вихідних дзвінків. Див. Використання власних номерів.

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

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

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

   Вихідні дзвінки повертають 402 Payment Required, якщо баланс ≤ $0.00. Поповніть баланс або ввімкніть автоматичне поповнення в розділі Organization → Billing Settings на панелі керування. Ваш ключ sk_live_ може перевіряти баланс за допомогою GET /v1/billing, але не може поповнювати баланс або змінювати автоматичне поповнення.

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

Найпростіший спосіб — указати агента за ідентифікатором:

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

Відповідь:

{ "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":   "+14155552671",
    "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 запису після завершення дзвінка.

Якщо ваш агент налаштований на вилучення структурованих даних після дзвінка, ці дані доставляються окремо після завершення фіналізації.

Передавання змінних для дзвінка збереженому агенту#

Збережені агенти можуть використовувати в тексті промпту заповнювачі на кшталт {{name}} або {{name|there}}. Коли ви здійснюєте вихідний дзвінок із agent_id, передайте variables зі значеннями для цього дзвінка:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Використовуйте рядкові значення з ключами, що відповідають назві заповнювача. Ці змінні застосовуються до збережених агентів; у вбудованому прикладі config у цьому посібнику вони не використовуються.

Важливі сценарії помилок#

Перегляньте довідник вихідних дзвінків, щоб отримати повний стабільний список кодів відповідності вимогам і обидві форми відповіді 409. Якщо активний номер стає невідповідним вимогам після прийняття запиту, але до здійснення дзвінка, остаточна перевірка повертає корисне навантаження 409, яке не можна повторити.

Керування часом очікування#

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

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

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

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