Open in
Користите 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 датотеком при њеној наведеној стопи. Проверите:
- Сервер прихвата конфигурацију и шаље
session.updated. - Улаз производи догађаје транскрипта и излазног звука очекиваном брзином.
- Прекид и отказивање одговора заустављају преостали излазни звук.
- Резултати уграђених функција или резултати алатки сачуваног агента враћају се моделу.
- Неважећи улаз производи догађај
errorкојим Ваш клијент рукује. - Ваш клијент затвара сокет, а позив се појављује у историји позива.
Референца за Realtime WebSocket наводи прихваћене догађаје, формате звука, поља сесије и потпуне примере.
Цена
Позиви у реалном времену се наплаћују као и сваки други позив: према цени њихових компоненти по каталошким ценама наших добављача, уз накнаду за инфраструктуру и маржу од 17–25%. Омогућавање разлика у транскрипту уживо додаје обраду транскрипције за целу сесију; погледајте Транскрипте уживо и Цене.
POST /v1/realtime/sessions је засебна управљана LiveKit путања. Она креира
собу и ограничени токен учесника; није потребна за директну WebSocket везу.
За интеграције са оквирима, погледајте Користите ThunderPhone из Pipecat-а и Користите ThunderPhone из LiveKit Agents-а.