Open in
OpenAI Realtime کلائنٹس کے ساتھ ThunderPhone استعمال کریں
محفوظ کردہ ایجنٹ یا اِن لائن سیشن کنفیگریشن استعمال کرتے ہوئے، OpenAI Realtime سے ہم آہنگ سرور کلائنٹ کو ThunderPhone کی طرف پوائنٹ کریں۔
ThunderPhone، OpenAI Realtime ایونٹ ماڈل کے ایک مخصوص ذیلی مجموعے کو نافذ کرتا ہے۔ ایک موجودہ سرور سائیڈ کلائنٹ، ThunderPhone وائس ایجنٹ استعمال کرتے ہوئے اپنا WebSocket، آڈیو، سیشن، اور جوابی ایونٹ فلو برقرار رکھ سکتا ہے۔
کنیکٹ کرنے سے پہلے
آپ کو ThunderPhone تنظیم کی خفیہ API کلید اور ایسا سرور رن ٹائم درکار ہے جو WebSockets کھول سکے۔ براؤزر کوڈ سے کنیکٹ نہ کریں اور کلید کو براؤزر کے سامنے ظاہر نہ کریں۔ محفوظ شدہ ایجنٹ استعمال کرنے کے لیے، پہلے اسے ڈیپلائے کریں اور اس کا عددی ایجنٹ ID کاپی کریں۔
یہاں کنیکٹ کریں:
wss://api.thunderphone.com/v1/realtimeاپنے سرور سے WebSocket اپ گریڈ کی توثیق کریں:
Authorization: Bearer sk_live_YOUR_API_KEYایسے کلائنٹس کے لیے query-string توثیق موجود ہے جو handshake ہیڈرز سیٹ نہیں کر سکتے، لیکن URLs کے لاگز میں ظاہر ہونے کا امکان زیادہ ہوتا ہے۔
منتخب کریں کہ کنفیگریشن کا مالک کون ہے
| موڈ | اسے منتخب کرنے کا طریقہ | کنفیگریشن کا ماخذ |
|---|---|---|
| محفوظ شدہ ایجنٹ | پہلی session.update میں session.prompt.id، یا ?agent_id=12 | ڈیپلائے کیا گیا prompt، آواز، پروڈکٹ، زبانیں، نالج، اور مطابقت رکھنے والے سرور پر چلنے والے ٹولز، نیز اس سیشن کی ہدایات اور ویری ایبلز |
| اِن لائن | کوئی بھی نہیں | آپ کے کلائنٹ کی پہلی قبول شدہ 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 ایونٹ کے ساتھ
مسترد کر دیے جاتے ہیں۔ اسے آپ کے پہلے session.update پر شروع کرنے کے لیے URL میں
&wait_for_session_update=1 شامل کریں، جو پھر اسی طریقے سے ہدایات، ویری ایبلز اور
سیشن اختیارات رکھتا ہے؛ آؤٹ باؤنڈ سیشن کے لیے یہ ضروری ہے۔ جب تک وہ اپ ڈیٹ نہ پہنچے،
کالر آڈیو روکی جاتی ہے، دیگر ایونٹس مسترد کر دیے جاتے ہیں، اور اگر 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 ایک کال کی نمائندگی کرتا ہے۔ غلط ایجنٹ ID یا مسترد شدہ اِن لائن کنفیگریشن ایک error ایونٹ پیدا کرتی ہے۔ سیشن کو فعال سمجھنے سے پہلے session.updated کا انتظار کریں۔ اصل ان پٹ اور آؤٹ پٹ فارمیٹس اور سیمپل ریٹس بیان کریں: PCM ریٹ میں عدم مطابقت ویلیڈیشن کی غلطی پیدا کرنے کے بجائے آڈیو کو بہت تیز یا بہت آہستہ چلاتی ہے۔
سیشن شروع ہونے کے بعد، جب آپ کی ایپلیکیشن کا کام مکمل ہو جائے تو ساکٹ کو درست طریقے سے بند کریں۔ اِن لائن سیشنز کلائنٹ کے ذریعے چلائے گئے فنکشنز استعمال کر سکتے ہیں۔ محفوظ شدہ ایجنٹ سیشنز ThunderPhone کے چلائے ہوئے مطابقت پذیر ٹولز استعمال کرتے ہیں، اور transfer_call (اور آؤٹ باؤنڈ سیشنز میں send_keypad_input) صرف call_events کے ساتھ پیش کرتے ہیں؛ آپ کا کلائنٹ ان call.* ایونٹس کو انجام دیتا ہے۔
انضمام کی جانچ کریں
کم سے کم Python WAV کلائنٹ اور اس کی بیان کردہ ریٹ پر ایک مونو PCM16 WAV سے آغاز کریں۔ تصدیق کریں:
- سرور کنفیگریشن قبول کرتا ہے اور
session.updatedبھیجتا ہے۔ - ان پٹ متوقع رفتار پر ٹرانسکرپٹ اور ریسپانس آڈیو ایونٹس پیدا کرتا ہے۔
- مداخلت اور ریسپانس منسوخی باقی ماندہ آؤٹ پٹ آڈیو کو روک دیتی ہیں۔
- اِن لائن فنکشن کے نتائج یا محفوظ کردہ ایجنٹ ٹول کے نتائج ماڈل کو واپس جاتے ہیں۔
- غلط ان پٹ ایک
errorایونٹ پیدا کرتا ہے جسے آپ کا کلائنٹ ہینڈل کرتا ہے۔ - آپ کا کلائنٹ ساکٹ بند کرتا ہے اور کال کال ہسٹری میں ظاہر ہوتی ہے۔
Realtime WebSocket حوالہ قبول شدہ ایونٹس، آڈیو فارمیٹس، سیشن فیلڈز، اور مکمل مثالوں کی فہرست فراہم کرتا ہے۔
لاگت
Realtime کالز کی قیمت کسی بھی دوسری کال کی طرح مقرر ہوتی ہے: ہمارے فراہم کنندگان کی فہرستی قیمتوں پر ان کے اجزاء کی لاگت، علاوہ ازیں انفراسٹرکچر چارج اور 17–25% مارجن۔ لائیو ٹرانسکرپٹ ڈیلٹاز فعال کرنے سے پورے سیشن کے لیے ٹرانسکرپشن کا کام شامل ہو جاتا ہے؛ لائیو ٹرانسکرپٹس اور قیمتیں دیکھیں۔
POST /v1/realtime/sessions ایک علیحدہ منظم LiveKit پاتھ ہے۔ یہ ایک روم اور محدود دائرۂ کار والا پارٹیسپنٹ ٹوکن بناتا ہے؛ براہ راست WebSocket کنکشن کے لیے اس کی ضرورت نہیں ہے۔
فریم ورک انضمامات کے لیے، Pipecat سے ThunderPhone استعمال کریں اور LiveKit Agents سے ThunderPhone استعمال کریں دیکھیں۔