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

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

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

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

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

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

Агент об’єднує промпт, голос і рівень продукту, які забезпечуватимуть дзвінок. Ви також можете встановити для агента обмеження дзвінка, як-от max_call_duration_seconds і ring_duration_seconds. Агенти також підтримують intro_clip і intro_ring_count, щоб відтворити попередньо записане вступне повідомлення та до двох сигналів виклику перед тим, як агент заговорить. Новим агентам також потрібен часовий пояс. Перегляньте Агенти, щоб дізнатися про всі поля конфігурації; мінімально потрібно:

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 із пулу 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. Номери ThunderPhone спочатку мають 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. До цього API відхилятиме таке призначення з помилкою 400.

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

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

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

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

Вхідні дзвінки зараховуються до ліміту вашої організації на одночасні дзвінки (за замовчуванням 20 дзвінків у процесі, спільний ліміт для вихідних, веб- і тестових дзвінків). Дзвінок, що надходить після досягнення ліміту, відхиляється до того, як агент відповість, і завершується, не тарифікується та реєструється як невдалий дзвінок із причиною завершення concurrent_call_limit_reached. Напишіть на support@thunderphone.com, якщо вам потрібен вищий ліміт.

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.

Якщо для вашого агента налаштовано поля вилучення, дані завершеного дзвінка також можуть містити структуровані вилучені дані.

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