ThunderPhone v3 је сада доступан.Почните самостално, већ од 2 ¢/мин.Прочитајте објаву

Connect tools & data

Користите ThunderPhone са OpenAI Realtime клијентима

Усмерите серверски клијент компатибилан са OpenAI Realtime ка ThunderPhone-у, користећи сачуваног агента или уграђену конфигурацију сесије.

ThunderPhone примењује усмерени подскуп OpenAI Realtime модела догађаја. Постојећи клијент на серверској страни може да задржи свој ток WebSocket, аудио, сесијских догађаја и догађаја одговора док користи ThunderPhone гласовног агента.

Пре повезивања

Потребни су Вам тајни API кључ ThunderPhone организације и серверско окружење за извршавање које може да отвори WebSocket везе. Немојте се повезивати из кода у прегледачу нити излагати кључ прегледачу. Да бисте користили сачуваног агента, прво га примените и копирајте његов нумерички ID агента.

Повежите се на:

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

Потврдите аутентичност WebSocket надоградње са свог сервера:

Authorization: Bearer sk_live_YOUR_API_KEY

Аутентификација путем стринга упита постоји за клијенте који не могу да поставе заглавља при успостављању везе, али URL-ови лакше доспевају у евиденције.

Изаберите ко управља конфигурацијом

РежимИзаберите га помоћуИзвор конфигурације
Сачувани агентsession.prompt.id у првом session.update или ?agent_id=12Објављени промпт, глас, производ, језици, знање и компатибилни алати које покреће сервер, као и упутства и променљиве ове сесије
У линијиНиједноПрви прихваћени session.update од Вашег клијента

Сачувани агент

Сачувајте оно што је заједничко сваком позиву у сачуваном агенту, где има верзије и скупове за тестирање, и пошаљите оно што се мења по сесији у првом session.update: session.prompt.id бира објављеног агента, session.instructions садржи упутства за ову сесију, а session.prompt.variables попуњава чуваре места {{name}} у упиту агента.

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {
      "id": "12",
      "variables": { "user_name": "Ada Park" }
    },
    "instructions": "Ada is a Costco member in Mountain View. Call the store and ask for today's opening hours.",
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    }
  }
}

Упутства постају контекст позива, додат после упита агента само за овај позив. Опције саме сесије (telephony, outbound, ivr_mode, call_events, placeholders) и језик на којем почиње (primary_language) налазе се у session.config, као и за уграђену сесију. Глас, производ и алати агента долазе из његове објављене конфигурације: глас, друга поставка агента или поље које важи само за OpenAI, као што је неподразумевани tool_choice у ажурирању, производи догађај error и занемарује се, а алати које извршава Ваш клијент се одбијају (алати које извршава клијент захтевају уграђену сесију). prompt.version се прихвата и занемарује. Погледајте Користите сачуваног агента за сва правила.

Повезивање помоћу ?agent_id=12 уместо тога покреће агента док се сокет повезује, тако да session.update није неопходан, али је конфигурација његове сесије тада непроменљива: упутства, променљиве и опције сесије (outbound, ivr_mode, telephony, placeholders, call_events) послате након тога одбијају се уз догађај error. Додајте &wait_for_session_update=1 у URL да бисте га уместо тога покренули при првом session.update, који тада на исти начин садржи упутства, променљиве и опције сесије; одлазна сесија то захтева. Док то ажурирање не стигне, аудио позиваоца се задржава, други догађаји се одбијају, а сокет се затвара ако ниједно не стигне у року од 10 секунди.

Поздравна порука остаје доступна, али Realtime онемогућава говорне провере током тишине агента и нуди transfer_call и send_keypad_input само уз call_events. Други компатибилни алати извршавају се на ThunderPhone; алати које извршава клијент захтевају уграђену сесију. Формати звука, као ни упутства и променљиве сесије, не могу се мењати након почетка позива.

Уметнута сесија

Без сачуваног агента, сачекајте session.created, а затим пошаљите 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"
    }
  }
}

Прво прихваћено ажурирање успоставља позив. session.updated значи да је сесија активна. Упутства, глас, производ, алати и аудио-формати не могу се мењати након те тачке. Да би упутства остала непромењена, а да се мењају само именоване вредности, у њих упишите чуваре места {{name}} и пошаљите вредности у session.config.variables.

Уметнуте сесије немају аутоматски поздрав нити говорне провере тишине. Да би агент први проговорио, додајте системску или корисничку поруку и пошаљите response.create. Потпуно неактивна сесија се и даље завршава на ограничењу платформе за тихе позиве, које подразумевано износи 600 секунди.

Користите званични OpenAI SDK

Проследите основни WebSocket URL који се завршава са /v1; SDK додаје /realtime. Вредност model је назив за компатибилност и не бира ThunderPhone производ. Изаберите производ у конфигурацији сесије или сачуваном агенту.

Ова провера везе креира уграђену Bolt сесију, исписује догађаје до првог session.updated и затвара се. Користите минимални 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 и нуде transfer_call (као и send_keypad_input у одлазним сесијама) само уз call_events; ваш клијент извршава те call.* догађаје.

Тестирајте интеграцију

Почните са минималним Python WAV клијентом и моно PCM16 WAV датотеком при њеној наведеној стопи. Проверите:

  1. Сервер прихвата конфигурацију и шаље session.updated.
  2. Улаз производи догађаје транскрипта и излазног звука очекиваном брзином.
  3. Прекид и отказивање одговора заустављају преостали излазни звук.
  4. Резултати уграђених функција или резултати алатки сачуваног агента враћају се моделу.
  5. Неважећи улаз производи догађај error којим Ваш клијент рукује.
  6. Ваш клијент затвара сокет, а позив се појављује у историји позива.

Референца за Realtime WebSocket наводи прихваћене догађаје, формате звука, поља сесије и потпуне примере.

Цена

Позиви у реалном времену се наплаћују као и сваки други позив: према цени њихових компоненти по каталошким ценама наших добављача, уз накнаду за инфраструктуру и маржу од 17–25%. Омогућавање разлика у транскрипту уживо додаје обраду транскрипције за целу сесију; погледајте Транскрипте уживо и Цене.

POST /v1/realtime/sessions је засебна управљана LiveKit путања. Она креира собу и ограничени токен учесника; није потребна за директну WebSocket везу.

За интеграције са оквирима, погледајте Користите ThunderPhone из Pipecat-а и Користите ThunderPhone из LiveKit Agents-а.