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

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

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.

Следующие шаги#