> ## 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)

> Відповідайте на свій перший телефонний дзвінок за допомогою AI-агента за чотири REST-виклики.

Цей посібник покаже вам чотири REST-запити, потрібні, щоб відповісти
на ваш перший телефонний дзвінок за допомогою ШІ-агента.

<Info>
  Вам потрібен [обліковий запис ThunderPhone](https://app.thunderphone.com).
  Реєстрація безкоштовна й займає менш ніж хвилину. Віддаєте перевагу клікам замість curl?
  [Швидкий старт у панелі керування](/uk/quickstart-dashboard) дає змогу прийняти той самий
  перший дзвінок без написання коду.
</Info>

## Крок 1: Отримайте ключ API

<Steps>
  <Step title="Увійдіть">
    Відкрийте [app.thunderphone.com](https://app.thunderphone.com).
  </Step>

  <Step title="Перейдіть до розділу «Ключі»">
    У панелі керування перейдіть до **Організація → Ключі**.
  </Step>

  <Step title="Створіть ключ">
    Натисніть **Створити ключ**, задайте йому назву та скопіюйте
    значення `sk_live_...`. Ключ у відкритому вигляді показується **лише один раз** — негайно збережіть його
    у своєму сховищі секретів.
  </Step>
</Steps>

<Tip>
  Потрібна допомога? Посібник [Створення серверного ключа API](/uk/guides/api-keys)
  докладно описує цей процес покроково, а вбудований помічник може
  у реальному часі підсвітити для вас кожен елемент керування.
</Tip>

У цьому посібнику замінюйте `sk_live_YOUR_API_KEY` на значення, яке ви
щойно скопіювали. Ключ автоматично ідентифікує вашу організацію, тому
вам ніколи не потрібно додавати ідентифікатор організації в URL-адреси.

## Крок 2: Створіть агента

Агент визначає, як ШІ обробляє розмови — промпт, голос,
рівень продукту, інструменти та можливість використання у віджеті.

<CodeGroup>
  ```bash cURL 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":   "Customer Support",
      "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
      "voice":  "john",
      "product": "spark"
    }'
  ```

  ```python Python theme={null}
  import os, requests

  agent = requests.post(
      "https://api.thunderphone.com/v1/agents",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={
          "name":   "Customer Support",
          "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
          "voice":  "john",
          "product": "spark",
      },
  ).json()
  print("Agent id:", agent["id"])
  ```

  ```javascript Node.js theme={null}
  const agent = await fetch("https://api.thunderphone.com/v1/agents", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name:    "Customer Support",
      prompt:  "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
      voice:   "john",
      product: "spark",
    }),
  }).then((r) => r.json());
  console.log("Agent id:", agent.id);
  ```
</CodeGroup>

<Tip>
  Рівні продукту: `spark` оптимізовано для вартості, `bolt` — для швидкості, а
  `storm-base` / `storm-extra` — для інтелектуальної обробки складних промптів. Повне
  порівняння дивіться в розділі [Агенти](/api-reference/agents#product-tiers-at-a-glance).
</Tip>

## Крок 3: Виділіть номер телефону

Цей виклик запитує номер із демо-пулу ThunderPhone і призначає вашого
нового агента обробником вхідних викликів. (Щоб підключити власний номер від
VoIP-провайдера, натомість перегляньте [VoIP-з’єднання](/api-reference/voip-connections).)

<CodeGroup>
  ```bash cURL theme={null}
  # First provision
  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"}'

  # Then assign the agent you created in Step 2
  curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/<id-from-previous> \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"inbound_agent_id": 12}'
  ```

  ```python Python theme={null}
  number = requests.post(
      "https://api.thunderphone.com/v1/phone-numbers",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={"area_code": "415"},
  ).json()
  requests.patch(
      f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={"inbound_agent_id": agent["id"]},
  )
  print("Your ThunderPhone number:", number["number"])
  ```
</CodeGroup>

Ваш новий номер починає зі статусом `status="provisioning"` і за кілька секунд
переходить у статус `active`; до моменту, коли ви закриєте браузер, номер буде
готовий приймати виклики.

## Крок 4 (необов’язково): Налаштуйте вебхук

Для подій у реальному часі (динамічної маршрутизації викликів, обробки після
виклику) додайте кінцеву точку вебхука. Підписуйтеся лише на потрібні вам події.

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod webhook",
    "url":    "https://your-server.com/thunderphone-webhook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'
```

Відповідь містить одноразовий `secret` — скопіюйте його до свого менеджера
секретів. Використовуйте цей секрет для перевірки заголовка
`X-ThunderPhone-Signature` у вхідних запитах (див.
[Огляд вебхуків](/uk/webhooks/overview)).

## Крок 5: Протестуйте свого агента

Зателефонуйте на щойно виділений номер. Агент відповість, представиться
та дотримуватиметься вашого промпту.

Перегляньте виклик після його завершення:

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

Перейдіть до конкретного виклику, щоб отримати транскрипт і URL запису:

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

***

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

<CardGroup cols={2}>
  <Card title="Додайте інструменти-функції" icon="screwdriver-wrench" href="/uk/tools/overview">
    Дозвольте своєму агенту викликати ваші API під час розмови.
  </Card>

  <Card title="Здійснюйте вихідні виклики" icon="arrow-up-right" href="/api-reference/outbound-calls">
    Ініціюйте виклики з власного коду.
  </Card>

  <Card title="Обробляйте вебхуки" icon="bolt" href="/uk/webhooks/overview">
    Реагуйте на події викликів у реальному часі.
  </Card>

  <Card title="Повна довідка API" icon="book" href="/api-reference/introduction">
    Документація для кожної публічної кінцевої точки.
  </Card>
</CardGroup>