---
title: "Используйте ThunderPhone с клиентами OpenAI Realtime"
description: "Подключите клиент сервера, совместимый с OpenAI Realtime, к ThunderPhone, используя сохранённого голосового агента или встроенную конфигурацию сессии."
---

ThunderPhone реализует специализированное подмножество модели событий OpenAI Realtime.
Существующий серверный клиент может сохранить свой поток событий WebSocket, аудио, сессии и
ответов при использовании голосового агента ThunderPhone.

## Перед подключением

Вам нужен секретный API-ключ организации ThunderPhone и серверная среда выполнения,
которая может открывать WebSocket-соединения. Не подключайтесь из кода браузера и не
раскрывайте ключ в браузере. Чтобы использовать сохранённого агента, сначала разверните его
и скопируйте его числовой идентификатор.

Подключитесь к:

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

Аутентифицируйте обновление WebSocket на своём сервере:

```http
Authorization: Bearer sk_live_YOUR_API_KEY
```

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

## Выберите владельца конфигурации

| Режим | Подключение с | Источник конфигурации |
| --- | --- | --- |
| Сохранённый агент | `?agent_id=12` | Развёрнутые инструкции, голос, продукт, языки, база знаний и совместимые инструменты, выполняемые на сервере |
| Встроенный | Без `agent_id` | Первый принятый `session.update` от вашего клиента |

### Сохранённый агент

Подключитесь с идентификатором развёрнутого агента:

```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 соответствует одному звонку. Недопустимый идентификатор агента или отклонённая встроенная
конфигурация создаёт событие `error`. Дождитесь `session.updated`, прежде чем
считать сессию активной. Укажите фактические форматы входного и выходного аудио и
частоты дискретизации: несоответствие частоты PCM воспроизводит аудио слишком быстро или
слишком медленно вместо выдачи ошибки валидации.

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

## Проверьте интеграцию

Начните с [минимального WAV-клиента на Python](/api-reference/realtime#minimal-python-client)
и монофонического PCM16 WAV с указанной в нём частотой. Проверьте:

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

В [справочнике Realtime WebSocket](/api-reference/realtime) перечислены поддерживаемые
события, форматы аудио, поля сессии и полные примеры.

## Стоимость

Для звонков Realtime применяется обычная поминутная ставка выбранного продукта. Включение дельт
расшифровки в реальном времени добавляет поминутную доплату на всю сессию; ставку см. в разделе [Расшифровки в реальном времени](/api-reference/realtime#live-transcripts), а
ставки продуктов — в разделе [Тарифы](/ru/guides/pricing).

`POST /v1/realtime/sessions` — это отдельный управляемый путь LiveKit. Он создаёт
комнату и ограниченный токен участника; он не требуется для прямого подключения WebSocket.

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