--- title: "Używaj ThunderPhone z klientami OpenAI Realtime" description: "Skieruj klienta serwerowego zgodnego z OpenAI Realtime do ThunderPhone, używając zapisanego agenta lub wbudowanej konfiguracji sesji." --- ThunderPhone implementuje wybrany podzbiór modelu zdarzeń OpenAI Realtime. Istniejący klient po stronie serwera może zachować przepływ zdarzeń WebSocket, audio, sesji i odpowiedzi podczas korzystania z agenta głosowego ThunderPhone. ## Przed połączeniem Potrzebujesz tajnego klucza API organizacji ThunderPhone oraz środowiska uruchomieniowego serwera, które może otwierać połączenia WebSocket. Nie łącz się z kodu przeglądarki ani nie ujawniaj klucza przeglądarce. Aby użyć zapisanego agenta, najpierw go wdroż i skopiuj jego numeryczny identyfikator agenta. Połącz się z: ```text wss://api.thunderphone.com/v1/realtime ``` Uwierzytelnij aktualizację połączenia WebSocket z serwera: ```http Authorization: Bearer sk_live_YOUR_API_KEY ``` Uwierzytelnianie za pomocą parametrów zapytania jest dostępne dla klientów, które nie mogą ustawiać nagłówków uzgadniania połączenia, ale adresy URL łatwiej trafiają do dzienników. ## Wybierz właściciela konfiguracji | Tryb | Połącz z | Źródło konfiguracji | | --- | --- | --- | | Zapisany agent | `?agent_id=12` | Wdrożony prompt, głos, produkt, języki, wiedza i zgodne narzędzia uruchamiane na serwerze | | Wbudowany | Brak `agent_id` | Pierwsze zaakceptowane `session.update` od klienta | ### Zapisany agent Połącz się z wdrożonym identyfikatorem agenta: ```text wss://api.thunderphone.com/v1/realtime?agent_id=12 ``` Agent uruchamia się podczas łączenia gniazda. Jego powitanie pozostaje dostępne, ale Realtime wyłącza wypowiadane sprawdzenia ciszy oraz pomija `transfer_call` i `send_keypad_input`. Pozostałe zgodne narzędzia działają w ThunderPhone. Nie wysyłaj wbudowanych instrukcji ani narzędzi wykonywanych przez klienta w tym trybie. Ustaw formaty audio transmisji przed uruchomieniem agenta za pomocą parametrów zapytania `input_audio_format`, `output_audio_format`, `input_rate` i `output_rate`. Po połączeniu nie możesz zmienić zapisanej konfiguracji ani formatów audio. ### Sesja wbudowana Bez `agent_id` poczekaj na `session.created`, a następnie wyślij `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" } } } ``` Pierwsza zaakceptowana aktualizacja inicjuje połączenie. `session.updated` oznacza, że sesja jest aktywna. Po tym momencie nie można zmieniać instrukcji, głosu, produktu, narzędzi ani formatów audio. Sesje wbudowane nie mają automatycznego powitania ani wypowiadanych sprawdzeń ciszy. Aby agent odezwał się pierwszy, dodaj wiadomość systemową lub użytkownika i wyślij `response.create`. Całkowicie bezczynna sesja nadal kończy się po osiągnięciu limitu cichego połączenia platformy, który domyślnie wynosi 600 sekund. ## Użyj oficjalnego SDK OpenAI Przekaż bazowy adres URL WebSocket kończący się na `/v1`; SDK dodaje `/realtime`. Wartość `model` jest nazwą zgodności i nie wybiera produktu ThunderPhone. Wybierz produkt w konfiguracji sesji lub zapisanym agencie. To sprawdzenie połączenia tworzy wbudowaną sesję Bolt, drukuje zdarzenia do pierwszego `session.updated`, a następnie zamyka połączenie. Użyj [minimalnego klienta Python](/api-reference/realtime#minimal-python-client) do strumieniowania dźwięku. ```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()) ``` Zachowaj istniejącą obsługę dodawania wejściowego dźwięku, delt dźwięku odpowiedzi, przerwań, wywołań funkcji, błędów i prawidłowego zamykania gniazda. Wbudowane funkcje niestandardowe są wykonywane w kliencie; zwracaj ich wyniki przez protokół Realtime. Narzędzia zapisanego agenta są wykonywane w ThunderPhone. ## Cykl życia sesji i błędy Jeden WebSocket reprezentuje jedno połączenie. Nieprawidłowy identyfikator agenta lub odrzucona konfiguracja wbudowana powoduje zdarzenie `error`. Przed uznaniem sesji za aktywną poczekaj na `session.updated`. Określ rzeczywiste formaty wejściowe i wyjściowe oraz częstotliwości próbkowania: niezgodność częstotliwości PCM powoduje odtwarzanie dźwięku zbyt szybko lub zbyt wolno zamiast błędu walidacji. Po rozpoczęciu sesji prawidłowo zamknij gniazdo, gdy aplikacja zakończy działanie. Sesje wbudowane mogą używać funkcji wykonywanych przez klienta. Sesje zapisanych agentów używają zgodnych narzędzi uruchamianych przez ThunderPhone i nie obsługują przekazywania połączeń ani wprowadzania danych z klawiatury. ## Przetestuj integrację Zacznij od [minimalnego klienta Python WAV](/api-reference/realtime#minimal-python-client) i monofonicznego pliku WAV PCM16 z deklarowaną przez niego częstotliwością próbkowania. Sprawdź: 1. Serwer akceptuje konfigurację i wysyła `session.updated`. 2. Dane wejściowe generują zdarzenia transkrypcji i dźwięku odpowiedzi z oczekiwaną prędkością. 3. Przerwanie i anulowanie odpowiedzi zatrzymują pozostały dźwięk wyjściowy. 4. Wyniki funkcji wbudowanych lub narzędzi zapisanego agenta wracają do modelu. 5. Nieprawidłowe dane wejściowe generują zdarzenie `error`, które obsługuje klient. 6. Klient zamyka gniazdo, a połączenie pojawia się w [Historii połączeń](/pl/guides/review-calls). [Dokumentacja WebSocket Realtime](/api-reference/realtime) zawiera listę akceptowanych zdarzeń, formatów dźwięku, pól sesji i kompletne przykłady. ## Koszt Połączenia Realtime korzystają ze standardowej stawki minutowej wybranego produktu. Włączenie delt transkrypcji na żywo dodaje dopłatę za minutę dla całej sesji; stawkę znajdziesz w [Transkrypcjach na żywo](/api-reference/realtime#live-transcripts), a stawki produktów w [Cenniku](/pl/guides/pricing). `POST /v1/realtime/sessions` to osobna zarządzana ścieżka LiveKit. Tworzy pokój i token uczestnika o ograniczonym zakresie; nie jest wymagana do bezpośredniego połączenia WebSocket. Informacje o integracjach z frameworkami znajdziesz w [Używaj ThunderPhone z Pipecat](/pl/guides/use-with-pipecat) oraz [Używaj ThunderPhone z LiveKit Agents](/pl/guides/use-with-livekit).