Обработка входящих звонков (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. Напишите по email 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.

Если для вашего агента настроены поля извлечения, полезная нагрузка завершённого звонка также может включать структурированные извлечённые данные.

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