Gunakan ThunderPhone dengan klien OpenAI Realtime

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:

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

Autentikasi upgrade WebSocket dari server Anda:

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#

Agen tersimpan#

Terhubung dengan ID agen yang telah di-deploy:

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:

{
  "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 untuk melakukan streaming audio.

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 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.

Referensi WebSocket 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 untuk tarif dan Harga 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 dan Gunakan ThunderPhone dari LiveKit Agents.