---
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 секунди.

## Използвайте официалния OpenAI SDK

Подайте базов 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, и не предлагат прехвърляне или въвеждане от клавиатурата.

## Тествайте интеграцията

Започнете с [минималния Python WAV клиент](/api-reference/realtime#minimal-python-client)
и моно PCM16 WAV с обявената в него честота. Проверете:

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

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

## Цена

Realtime обажданията използват обичайната цена за минута на избрания продукт.
Включването на делти за транскрипция на живо добавя допълнителна цена за минута
за цялата сесия; вижте [Транскрипции на живо](/api-reference/realtime#live-transcripts)
за цената и [Цени](/bg/guides/pricing) за цените на продуктите.

`POST /v1/realtime/sessions` е отделен управляван път на LiveKit. Той създава
стая и токен за участник с ограничен обхват; не е необходим за директна WebSocket
връзка.

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