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

Подайте базов URL адрес за WebSocket, завършващ на /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 възпроизвежда аудиото твърде бързо или твърде бавно, вместо да предизвика грешка при валидирането.

След като сесията започне, затворете socket връзката коректно, когато приложението ви приключи. Вградените сесии могат да използват функции, изпълнявани от клиента. Сесиите със запазен агент използват съвместими инструменти, изпълнявани от 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.