> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Обрабатывайте входящие звонки (API)

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

<Note>
  Создаёте первого агента вручную? Панель управления проведёт вас по этому же
  процессу — создать агента, добавить номер, симулировать, проверить — с
  помощью пошагового мастера. Начните с
  [быстрого старта в панели управления](/ru/quickstart-dashboard).
</Note>

Канонический сценарий «ответить на звонок с помощью ИИ» из терминала.
Вы:

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

Всего API-вызовов: четыре. Общее время: менее пяти минут.

## 1. Создайте агента

Агент объединяет промпт, голос и продуктовый уровень, которые будут обрабатывать
звонок. Все поля конфигурации описаны в разделе [Агенты](/api-reference/agents);
минимальный набор:

```bash theme={null}
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.

<Tip>
  Выберите `spark` для простых вопросов и ответов с минимальной стоимостью,
  `bolt` — когда важнее всего скорость. Перейдите на `storm-base-with-ack`,
  когда вашему промпту требуется более глубокое рассуждение и допустима
  полусекундная заполняющая фраза, пока модель обдумывает ответ. См.
  [продуктовые уровни](/api-reference/agents#product-tiers-at-a-glance).
</Tip>

## 2. Получите номер телефона

Если вам нужен номер, на который можно просто позвонить, подключите демо-номер
из пула ThunderPhone:

```bash theme={null}
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}`](/api-reference/phone-numbers#retrieve-a-phone-number).

<Note>
  Для продакшена не используйте демо-номера и
  [подключите собственные номера через VoIP](/ru/guides/bring-your-own-numbers).
  Демо-номера доступны только для входящих звонков и имеют ограничение по объёму.
</Note>

## 3. Назначьте агента

Свяжите агента из шага 1 с входящим направлением номера:

```bash theme={null}
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`](/api-reference/calls#list-calls) со
`status="in_progress"`. После завершения запись обновится полями
`end_reason`, `duration_seconds`, `billable_minutes`, а также (позже)
URL записи и оценкой ИИ.

## 5. Проверьте результаты

Получите список недавних звонков:

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Получите расшифровку:

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

И URL записи (краткосрочный, подписанный):

```bash theme={null}
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).

***

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

<CardGroup cols={2}>
  <Card title="Динамическая конфигурация для каждого звонка" icon="bolt" href="/ru/guides/dynamic-call-config">
    Выбирайте разных агентов для звонящих на основе номера телефона или
    пользовательской логики в вебхуке.
  </Card>

  <Card title="Добавление интеграций с инструментами" icon="screwdriver-wrench" href="/ru/guides/build-tool-integration">
    Разрешите агенту вызывать ваши API в ходе разговора.
  </Card>

  <Card title="Получение вебхуков call.complete" icon="bolt" href="/ru/webhooks/call-complete">
    Передавайте данные о каждом завершённом звонке в вашу CRM / систему аналитики.
  </Card>

  <Card title="Оценка ИИ и отчёты о проблемах" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Автоматически оценивайте каждый звонок и направляйте помеченные на проверку.
  </Card>
</CardGroup>