---
title: "Gunakan ThunderPhone dengan klien OpenAI Realtime"
description: "Arahkan klien server yang kompatibel dengan OpenAI Realtime ke ThunderPhone, menggunakan agen tersimpan atau konfigurasi sesi inline."
---

ThunderPhone mengimplementasikan subset terfokus dari model event OpenAI Realtime.
Klien sisi server yang sudah ada dapat mempertahankan alur event WebSocket, audio, sesi, dan
responsnya saat menggunakan agen suara AI ThunderPhone.

## Sebelum Anda terhubung

Anda memerlukan kunci API rahasia organisasi ThunderPhone dan runtime server yang
dapat membuka WebSocket. Jangan terhubung dari kode browser atau mengekspos kunci ke
browser. Untuk menggunakan agen tersimpan, deploy terlebih dahulu lalu salin ID agen numeriknya.

Terhubung ke:

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

Autentikasi upgrade WebSocket dari server Anda:

```http
Authorization: Bearer sk_live_YOUR_API_KEY
```

Autentikasi string kueri tersedia untuk klien yang tidak dapat menetapkan header
handshake, tetapi URL lebih mudah bocor ke log.

## Pilih pemilik konfigurasi

| Mode | Terhubung dengan | Sumber konfigurasi |
| --- | --- | --- |
| Agen tersimpan | `?agent_id=12` | Prompt, suara, produk, bahasa, pengetahuan, dan tool kompatibel yang dijalankan server yang telah di-deploy |
| Inline | Tanpa `agent_id` | `session.update` pertama dari klien Anda yang diterima |

### Agen tersimpan

Terhubung dengan ID agen yang telah di-deploy:

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

Agen dimulai saat soket terhubung. Sapaannya tetap tersedia,
tetapi Realtime menonaktifkan pemeriksaan diam yang diucapkan dan menghilangkan `transfer_call`
serta `send_keypad_input`. Tool kompatibel lainnya berjalan di ThunderPhone. Jangan
kirim instruksi inline atau tool yang dijalankan klien untuk mode ini.

Tetapkan audio wire sebelum agen dimulai dengan parameter kueri `input_audio_format`,
`output_audio_format`, `input_rate`, dan `output_rate`. Anda
tidak dapat mengubah konfigurasi tersimpan atau format audio setelah terhubung.

### Sesi inline

Tanpa `agent_id`, tunggu `session.created`, lalu kirim `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"
    }
  }
}
```

Pembaruan pertama yang diterima akan mengonfigurasikan panggilan. `session.updated` berarti
sesi aktif. Instruksi, suara, produk, tool, dan format audio tidak dapat
diubah setelah titik tersebut.

Sesi inline tidak memiliki sapaan otomatis atau pemeriksaan diam yang diucapkan. Untuk
membuat agen berbicara lebih dulu, tambahkan pesan sistem atau pengguna dan kirim
`response.create`. Sesi yang sepenuhnya diam tetap berakhir pada batas panggilan diam Platform,
600 detik secara default.

## Gunakan SDK OpenAI resmi

Berikan URL dasar WebSocket yang berakhir dengan `/v1`; SDK menambahkan `/realtime`. Nilai
`model` adalah nama kompatibilitas dan tidak memilih produk ThunderPhone.
Pilih produk dalam konfigurasi sesi atau agen tersimpan.

Pemeriksaan koneksi ini membuat sesi Bolt inline, mencetak peristiwa hingga
`session.updated` pertama, lalu menutupnya. Gunakan [klien Python
minimal](/api-reference/realtime#minimal-python-client) untuk melakukan streaming audio.

```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())
```

Pertahankan penanganan Anda yang sudah ada untuk penambahan audio input, delta audio
respons, interupsi, pemanggilan fungsi, kesalahan, dan penutupan socket yang bersih. Fungsi khusus inline
dieksekusi di klien Anda; kembalikan hasilnya melalui protokol Realtime.
Alat agen tersimpan dieksekusi di ThunderPhone.

## Siklus hidup sesi dan kegagalan

Satu WebSocket mewakili satu panggilan. ID agen yang tidak valid atau konfigurasi inline
yang ditolak menghasilkan peristiwa `error`. Tunggu `session.updated` sebelum
menganggap sesi aktif. Nyatakan format input dan output serta laju sampel yang sebenarnya:
ketidaksesuaian laju PCM memutar audio terlalu cepat atau terlalu lambat alih-alih
menghasilkan kesalahan validasi.

Setelah sesi dimulai, tutup socket dengan bersih saat aplikasi Anda selesai. Sesi inline
dapat menggunakan fungsi yang dieksekusi oleh klien. Sesi agen tersimpan
menggunakan alat kompatibel yang dijalankan ThunderPhone dan tidak menawarkan transfer atau input keypad.

## Uji integrasi

Mulai dengan [klien WAV Python minimal](/api-reference/realtime#minimal-python-client)
dan WAV PCM16 mono pada laju yang dinyatakannya. Verifikasi:

1. Server menerima konfigurasi dan mengirim `session.updated`.
2. Input menghasilkan peristiwa transkrip dan audio respons pada kecepatan yang diharapkan.
3. Interupsi dan pembatalan respons menghentikan audio output yang tersisa.
4. Hasil fungsi inline atau hasil alat agen tersimpan dikembalikan ke Model.
5. Input tidak valid menghasilkan peristiwa `error` yang ditangani klien Anda.
6. Klien Anda menutup socket dan panggilan muncul di [Riwayat
   panggilan](/id/guides/review-calls).

[Referensi WebSocket Realtime](/api-reference/realtime) mencantumkan
peristiwa yang diterima, format audio, kolom sesi, dan contoh lengkap.

## Biaya

Panggilan Realtime menggunakan tarif per menit normal produk yang dipilih. Mengaktifkan delta
transkrip langsung menambahkan biaya tambahan per menit untuk seluruh sesi; lihat [Transkrip
langsung](/api-reference/realtime#live-transcripts) untuk tarif dan
[Harga](/id/guides/pricing) untuk tarif produk.

`POST /v1/realtime/sessions` adalah jalur LiveKit terkelola yang terpisah. Jalur ini membuat
ruang dan token peserta dengan cakupan tertentu; jalur ini tidak diperlukan untuk koneksi WebSocket
langsung.

Untuk integrasi framework, lihat [Gunakan ThunderPhone dari Pipecat](/id/guides/use-with-pipecat)
dan [Gunakan ThunderPhone dari LiveKit Agents](/id/guides/use-with-livekit).