---
title: "Обработка входящих звонков (API)"
description: "Полный цикл: настройте агента, назначьте его номеру телефона, примите звонок и просмотрите расшифровку."
---
Создаёте первого агента вручную? В панели управления этот же процесс —
создание агента, добавление номера, симуляция, проверка — проводится
с помощью пошагового мастера. Начните с
[быстрого старта в панели управления](/ru/quickstart-dashboard).
Канонический сценарий «ответить на звонок с помощью ИИ» из терминала.
Вы:
1. Создадите агента с промптом и голосом.
2. Выделите (или подключите) телефонный номер и назначите агента его
обработчиком входящих звонков.
3. Позвоните на номер. Просмотрите журнал звонков, расшифровку и запись.
Всего API-вызовов: четыре. Общее время: менее пяти минут.
## 1. Создайте агента
Агент объединяет промпт, голос и уровень продукта, которые будут использоваться
во время звонка. Для агента также можно задать ограничения звонка, например `max_call_duration_seconds`
и `ring_duration_seconds`. Агенты также поддерживают `intro_clip`
и `intro_ring_count`, чтобы воспроизвести заранее записанное вступление и до двух гудков перед тем,
как агент начнёт говорить. Для новых агентов также необходимо указать часовой пояс.
Все поля конфигурации см. в разделе [Агенты](/api-reference/agents); минимальная конфигурация:
```bash
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.
Выберите `spark` для простых вопросов и ответов с минимальной стоимостью,
`bolt` — когда важнее всего скорость. Перейдите на `storm-base-with-ack`,
если вашему промпту требуется более глубокое рассуждение и допустима
полусекундная заполняющая фраза, пока модель думает. См.
[тарифы продукта](/api-reference/agents#product-tiers-at-a-glance).
## 2. Получите телефонный номер
Если вам нужен номер, на который можно просто позвонить, получите номер
ThunderPhone из пула ThunderPhone:
```bash
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}`](/api-reference/phone-numbers#retrieve-a-phone-number).
Номера ThunderPhone изначально поддерживают только входящие звонки. Администратор
организации может запросить исходящие звонки на странице «Телефонные номера».
ThunderPhone вручную проверяет каждый запрос; после одобрения номера смогут
совершать звонки и запускать кампании. VoIP-номера клиентов не изменяются.
## 3. Назначьте агента
Свяжите агента с этапа 1 с входящим направлением номера:
```bash
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`](/api-reference/calls#list-calls) со
`status="in_progress"`. После завершения запись обновляется полями
`end_reason`, `duration_seconds`, `billable_minutes` и, позднее,
URL записи и оценкой ИИ.
Входящие вызовы учитываются в
[лимите одновременных вызовов](/api-reference/introduction#call-limits) вашей организации (по умолчанию 20
вызовов в процессе, общий лимит для исходящих, веб- и тестовых
вызовов). Вызов, поступивший при достижении лимита, отклоняется до ответа
агента и завершается, не тарифицируется и регистрируется как неуспешный вызов
с причиной завершения `concurrent_call_limit_reached`. Напишите по email support@thunderphone.com, если вам
нужен более высокий лимит.
## 5. Проверьте результаты
Получите список последних звонков:
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Получите расшифровку:
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
И URL записи (временный, с подписью):
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Если вы подписались на
[вебхук `telephony.complete`](/ru/webhooks/events),
вы получите те же данные в виде POST-запроса на свой сервер — см.
[call.complete](/ru/webhooks/call-complete).
Если для вашего агента настроены поля извлечения, полезная нагрузка завершённого
звонка также может включать структурированные извлечённые данные.
---
## Следующие шаги
Выбирайте разных агентов для каждого звонящего по номеру телефона или
с помощью пользовательской логики в вебхуке.
Позвольте агенту вызывать ваши API во время разговора.
Направляйте звонящих напрямую или проверяйте получателя перед соединением.
Передавайте данные каждого завершённого звонка в CRM или конвейер аналитики.
Автоматически оценивайте каждый звонок и направляйте отмеченные для проверки.