> ## 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>
  Створюєте першого агента вручну? Панель керування проведе вас точно
  цим процесом — створення агента, додавання номера, симуляція, перевірка —
  за допомогою покрокового майстра. Почніть із
  [швидкого старту в панелі керування](/uk/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](/uk/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}'
```

Готово — номер активний. Ви також можете встановити `outbound_agent_id`
у тому самому PATCH, щоб номер був готовий і для вихідних викликів.

## 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`](/uk/webhooks/events),
ви отримаєте ті самі дані як POST-запит на свій сервер — див.
[call.complete](/uk/webhooks/call-complete).

***

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

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

  <Card title="Додайте інтеграції інструментів" icon="screwdriver-wrench" href="/uk/guides/build-tool-integration">
    Дозвольте агенту викликати ваші API під час розмови.
  </Card>

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

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