Developer cookbook

Обробка вхідних дзвінків (API)

Повний цикл: налаштуйте агента, призначте його номеру телефону, прийміть дзвінок і перегляньте транскрипт.

Стандартний сценарій «відповісти на дзвінок за допомогою ШІ» з вашого термінала. Ви:

1. Створите агента з промптом і голосом.
2. Виділите (або підключите власний) номер телефону та призначите агента обробником вхідних викликів.
3. Зателефонуєте на номер. Переглянете журнал викликів, транскрипт і запис.

Усього API-викликів: чотири. Загальний час: менше п’яти хвилин.

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

Агент об’єднує промпт, голос і рівень продукту, які керуватимуть викликом. Перегляньте Агенти, щоб дізнатися про всі поля конфігурації; мінімальна конфігурація:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Збережіть повернений id — він знадобиться на кроці 2.

2. Отримайте номер телефону#

Якщо вам просто потрібен номер для дзвінків, виділіть демонстраційний номер із пулу ThunderPhone:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

Відповідь містить id і number у форматі E.164. Демонстраційні номери починають зі status="provisioning" і протягом кількох секунд стають active — за потреби періодично надсилайте GET /v1/phone-numbers/{id}, щоб відстежувати зміну статусу.

3. Призначте агента#

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

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Готово — номер активний. Ви також можете встановити outbound_agent_id у тому самому PATCH, щоб номер був готовий і для вихідних викликів.

4. Прийміть виклик#

Зателефонуйте на номер зі свого телефона. Агент відповість, представиться відповідно до вашого промпту, і розмова почнеться.

Поки виклик триває, він відображається в GET /v1/calls зі status="in_progress". Коли він завершиться, запис оновиться полями end_reason, duration_seconds, billable_minutes і (згодом) URL запису та оцінкою ШІ.

5. Перевірте результати#

Отримайте список останніх викликів:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Отримайте транскрипт:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

І URL запису (тимчасовий, підписаний):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Якщо ви підписалися на вебхук telephony.complete, ви отримаєте ті самі дані як POST-запит на свій сервер — див. call.complete.

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