---
title: "Використання ThunderPhone із клієнтами OpenAI Realtime"
description: "Спрямуйте сумісний із OpenAI Realtime серверний клієнт до ThunderPhone, використовуючи збереженого агента або вбудовану конфігурацію сесії."
---

ThunderPhone реалізує цільову підмножину моделі подій OpenAI Realtime.
Наявний серверний клієнт може зберегти свій потік подій WebSocket, аудіо, сесії та
відповідей під час використання голосового агента ThunderPhone.

## Перед підключенням

Вам потрібні секретний API-ключ організації ThunderPhone і серверне середовище виконання,
яке може відкривати WebSocket-з’єднання. Не підключайтеся з коду браузера та не розкривайте
ключ у браузері. Щоб використовувати збереженого агента, спочатку розгорніть його та скопіюйте його числовий ID агента.

Підключайтеся до:

```text
wss://api.thunderphone.com/v1/realtime
```

Автентифікуйте оновлення WebSocket-з’єднання зі свого сервера:

```http
Authorization: Bearer sk_live_YOUR_API_KEY
```

Автентифікація через рядок запиту доступна для клієнтів, які не можуть установити заголовки
рукостискання, але URL-адреси легше потрапляють до журналів.

## Виберіть, кому належить конфігурація

| Режим | Підключення через | Джерело конфігурації |
| --- | --- | --- |
| Збережений агент | `?agent_id=12` | Розгорнутий промпт, голос, продукт, мови, база знань і сумісні інструменти, що запускаються на сервері |
| Вбудований | Без `agent_id` | Перше прийняте `session.update` від вашого клієнта |

### Збережений агент

Підключіться за допомогою ID розгорнутого агента:

```text
wss://api.thunderphone.com/v1/realtime?agent_id=12
```

Агент запускається під час підключення сокета. Його привітання залишається доступним,
але Realtime вимикає голосові перевірки тиші та не включає `transfer_call`
і `send_keypad_input`. Інші сумісні інструменти запускаються на ThunderPhone. Не
надсилайте для цього режиму вбудовані інструкції або інструменти, що виконуються клієнтом.

Установіть аудіоформати передавання до запуску агента за допомогою параметрів запиту
`input_audio_format`, `output_audio_format`, `input_rate` і `output_rate`. Ви
не можете змінити збережену конфігурацію або аудіоформати після підключення.

### Вбудована сесія

Без `agent_id` дочекайтеся `session.created`, а потім надішліть `session.update`:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Answer questions clearly and keep responses brief.",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 }
      },
      "output": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "voice": "olivia"
      }
    },
    "config": {
      "product": "bolt"
    }
  }
}
```

Перше прийняте оновлення створює дзвінок. `session.updated` означає, що
сесія активна. Після цього інструкції, голос, продукт, інструменти й аудіоформати
не можна змінити.

Вбудовані сесії не мають автоматичного привітання або голосових перевірок тиші. Щоб
агент заговорив першим, додайте системне або користувацьке повідомлення та надішліть
`response.create`. Повністю неактивна сесія все одно завершується після досягнення
ліміту тихого дзвінка платформи — за замовчуванням через 600 секунд.

## Використовуйте офіційний SDK OpenAI

Передайте базову URL-адресу WebSocket, що закінчується на `/v1`; SDK додасть `/realtime`. Значення
`model` є назвою для сумісності й не визначає продукт ThunderPhone.
Виберіть продукт у конфігурації сесії або збереженому агенті.

Ця перевірка з’єднання створює вбудовану сесію Bolt, виводить події до першої
`session.updated` і закривається. Використовуйте [мінімальний клієнт
Python](/api-reference/realtime#minimal-python-client) для потокової передачі аудіо.

```python
import asyncio
import os

from openai import AsyncOpenAI


async def main():
    client = AsyncOpenAI(
        api_key=os.environ["THUNDERPHONE_API_KEY"],
        websocket_base_url="wss://api.thunderphone.com/v1",
    )

    async with client.realtime.connect(
        model="thunderphone-realtime"
    ) as connection:
        await connection.session.update(session={
            "type": "realtime",
            "instructions": "Listen to the caller and help them complete the call.",
            "config": {"product": "bolt"},
        })
        async for event in connection:
            print(event.type)
            if event.type == "session.updated":
                break


if __name__ == "__main__":
    asyncio.run(main())
```

Збережіть наявну обробку додавання вхідного аудіо, дельт аудіо відповіді,
переривань, викликів функцій, помилок і коректного закриття сокета. Вбудовані користувацькі
функції виконуються у вашому клієнті; повертайте їхні результати через протокол
Realtime. Інструменти збереженого агента виконуються в ThunderPhone.

## Життєвий цикл сесії та збої

Один WebSocket відповідає одному дзвінку. Недійсний ID агента або відхилена вбудована
конфігурація створює подію `error`. Дочекайтеся `session.updated`, перш ніж
вважати сесію активною. Укажіть фактичні формати вводу й виводу та
частоти дискретизації: невідповідність частоти PCM відтворює аудіо надто швидко або надто повільно замість
створення помилки перевірки.

Після запуску сесії коректно закрийте сокет, коли ваша програма
завершить роботу. Вбудовані сесії можуть використовувати функції, що виконуються клієнтом. Сесії
збереженого агента використовують сумісні інструменти, що виконуються ThunderPhone, і не підтримують
переадресацію або введення з клавіатури телефону.

## Перевірте інтеграцію

Почніть із [мінімального клієнта Python для WAV](/api-reference/realtime#minimal-python-client)
та монофонічного WAV PCM16 із заявленою частотою. Перевірте:

1. Сервер приймає конфігурацію та надсилає `session.updated`.
2. Введення створює події транскрипту й аудіо відповіді з очікуваною швидкістю.
3. Переривання та скасування відповіді зупиняють решту вихідного аудіо.
4. Результати вбудованих функцій або інструментів збереженого агента повертаються моделі.
5. Недійсне введення створює подію `error`, яку обробляє ваш клієнт.
6. Ваш клієнт закриває сокет, а дзвінок з’являється в [історії
   дзвінків](/uk/guides/review-calls).

У [довіднику Realtime WebSocket](/api-reference/realtime) наведено підтримувані
події, аудіоформати, поля сесії та повні приклади.

## Вартість

Дзвінки Realtime використовують звичайну похвилинну ставку вибраного продукту. Увімкнення дельт
транскрипту в реальному часі додає похвилинну доплату за всю сесію; дивіться [транскрипти в реальному
часі](/api-reference/realtime#live-transcripts), щоб дізнатися ставку, і
[ціни](/uk/guides/pricing), щоб переглянути ставки продуктів.

`POST /v1/realtime/sessions` — це окремий керований шлях LiveKit. Він створює
кімнату та токен учасника з обмеженою областю дії; він не потрібен для прямого з’єднання WebSocket.

Для інтеграцій із фреймворками дивіться [Використовуйте ThunderPhone з Pipecat](/uk/guides/use-with-pipecat)
і [Використовуйте ThunderPhone з LiveKit Agents](/uk/guides/use-with-livekit).