Open in
ویب ویجیٹ ایمبیڈ کریں
ایک ہی اسکرپٹ ٹیگ کے ذریعے اپنی مارکیٹنگ یا سپورٹ سائٹ پر ایک وائس ایجنٹ شامل کریں — وزیٹرز فون نمبر کے بغیر براہِ راست براؤزر سے اس سے بات کر سکتے ہیں۔
ویب ویجٹ آپ کی سائٹ کے وزیٹرز کو براؤزر کے مائیکروفون کے ذریعے AI وائس ایجنٹ کے ساتھ کلک کر کے بات کرنے کی گفتگو فراہم کرتا ہے۔ یہ اپنا الگ JavaScript / React SDK ہے جس کا اپنا SDK حوالہ ہے — یہ گائیڈ ویجٹ کے لیے درکار ThunderPhone کی طرف کی سیٹ اپ پر مرکوز ہے۔
ضروری شرائط
- ایک ایجنٹ بنائیں
وہ ایجنٹ جس کا prompt اور آواز وِجٹ سیشن چلائیں گے۔
widget_enabled: true(طے شدہ) سیٹ کریں۔ - روٹنگ موڈ طے کریں
mode="agent"— ہر کلید کے لیے ایک جامد ایجنٹ۔ سب سے آسان۔mode="webhook"— آپ کا سرور ہر وزیٹر کے لیے ایجنٹ منتخب کرتا ہےweb.incomingwebhook کے ذریعے۔ اسے لاگ اِن صارفین، A/B ٹیسٹس، یا ہر صفحے کی روٹنگ کے لیے استعمال کریں۔
- اجازت یافتہ ڈومینز کی فہرست بنائیں
ہر اُس ہوسٹ نیم کا نام درج کریں جو وِجٹ ایمبیڈ کرے گا۔ براؤزر ہر سیشن درخواست کے ساتھ صفحے کا ماخذ بھیجتے ہیں، اس لیے یہ فہرست آپ کی کلید کو اس وقت کام کرنے سے روکتی ہے جب کوئی اسے کسی دوسری سائٹ پر کاپی کرے۔ یہ تصدیقِ شناخت نہیں ہے: براؤزر سے باہر موجود ایک اسکرپٹ کوئی بھی
Originہیڈر بھیج سکتی ہے۔ پروڈکشن میںlocalhostخودکار طور پر اجازت یافتہ نہیں ہے؛ پروڈکشن API کے خلاف مقامی طور پر ٹیسٹ کرنے کے لیے،localhostکو فہرست میں شامل کریں۔ - براؤزر اووررائیڈز منتخب کریں
طے کریں کہ آپ کا صفحہ کن سیشن ترتیبات کو بھیج سکتا ہے۔ نئی کلیدیں کسی اووررائیڈ کو قبول نہیں کرتیں؛ براؤزر اووررائیڈز دیکھیں۔
شائع کرنے کے قابل کلید بنائیں
curl -X POST https://api.thunderphone.com/v1/publishable-key \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketing site (prod)",
"mode": "agent",
"agent_id": 12,
"allowed_domains": ["example.com", "*.example.com"],
"allowed_overrides": ["context"]
}'curl -X POST https://api.thunderphone.com/v1/publishable-key \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support (dynamic)",
"mode": "webhook",
"webhook_url": "https://example.com/thunderphone/widget-hook",
"allowed_domains": ["support.example.com"]
}'جواب میں pk_live_... سے شروع ہونے والی ایک key شامل ہوتی ہے۔ شائع کرنے کے قابل
کلیدیں ڈیزائن کے لحاظ سے عوامی ہیں — انہیں اپنے فرنٹ اینڈ بنڈل میں شامل کرنا محفوظ ہے۔
تمام فیلڈز کے لیے شائع کرنے کے قابل کلیدوں کا حوالہ دیکھیں۔
اپنی سائٹ پر ویجٹ شامل کریں
ویجٹ SDK دستاویزات میں انضمام کے تین اختیارات شامل ہیں:
<ThunderPhoneWidget publishableKey="pk_live_..." />.
حسب ضرورت UIs کے لیے useThunderPhone()۔
نان بنڈلر سائٹس کے لیے ThunderPhone.mount({...})۔
تینوں ایک ہی publishableKey قبول کرتے ہیں اور مائیک بٹن
کے ساتھ کال کے دوران آڈیو عنصر رینڈر کرتے ہیں۔
براؤزر اووررائیڈز
ویجٹ صفحے سے فی سیشن چار ترتیبات بھیج سکتا ہے:
| ترتیب | ویجٹ prop | اس سے کیا تبدیل ہوتا ہے |
|---|---|---|
context | context | صفحے کا متن، بطور حوالہ ایجنٹ کے prompt میں شامل کیا جاتا ہے |
variables | کوئی نہیں (صرف raw POST /v1/widget/session) | prompt میں موجود {{variable}} پلیس ہولڈرز کی قدریں |
voice | voice | اس سیشن کے لیے ایجنٹ کی آواز |
language | language | وہ زبان جس میں سیشن شروع ہوتا ہے |
آپ کی پبلش ایبل کلید عوامی ہے، اس لیے جس کے پاس بھی یہ ہو وہ یہ
ترتیبات بھیج سکتا ہے، بشمول ایسے اسکرپٹ سے جو آپ کے ڈومین کی نقل کرتا ہو۔ لہٰذا ہر ترتیب
اس وقت تک بند رہتی ہے جب تک آپ اسے کلید پر اجازت نہ دے دیں: ڈیش بورڈ میں ویجیٹ بناتے یا ترمیم کرتے وقت اسے براؤزر اووررائیڈز کے تحت منتخب کریں، یا
allowed_overrides کو
پبلش ایبل کلیدوں کی API کے ذریعے سیٹ کریں۔ صرف اسی کی اجازت دیں
جو آپ کا صفحہ واقعی بھیجتا ہے۔
ایسی سیشن درخواست جس میں وہ ترتیب ہو جس کی key اجازت نہیں دیتی،
400 کے ساتھ ناکام ہوتی ہے اور اس ترتیب کا نام بتاتی ہے:
{
"error": "override_not_allowed",
"fields": ["voice"],
"message": "This publishable key does not allow the browser to set `voice`. ..."
}یہ جانچ دونوں موڈز میں لاگو ہوتی ہے۔ ویب ہک موڈ میں، اجازت یافتہ ترتیب
آپ کے web.incoming ویب ہک کو بھی فارورڈ کی جاتی ہے (context بطور
website_context پہنچتا ہے)۔ اس ترتیب کے موجود ہونے سے پہلے بنائی گئی keys
تمام چار کی اجازت دیتی ہیں، اس لیے موجودہ embeds کام کرتے رہتے ہیں؛ جو استعمال نہیں کرتے اسے بند کر دیں۔
Widget کا context 12,000 حروف پر مختصر کر دیا جاتا ہے (عام انگریزی متن کے تقریباً 3,400
ٹوکنز) اور یہ اس prompt کا حصہ ہوتا ہے جسے ماڈلز پڑھتے ہیں، اس لیے
طویل context فی منٹ زیادہ لاگت رکھتا ہے۔
ایجنٹ کو ہدایت دی جاتی ہے کہ اسے ہدایات کے بجائے صفحے کے مواد کے طور پر سمجھے۔
ویجٹ موڈ ویب ہکس
جب mode="webhook" ہو تو ThunderPhone ہر
سیشن کے آغاز پر web.incoming payload کے ساتھ آپ کے webhook_url کو کال کرتا ہے۔ اس وزیٹر کے لیے
وہ ایجنٹ کنفیگریشن واپس کریں جسے آپ چلانا چاہتے ہیں — یہ فون
کالز جیسی ہی جواب اسکیما کی پیروی کرتا ہے:
{
"prompt": "You are a VIP concierge for Jane Doe.",
"voice": "john",
"product": "storm-base",
"tools": [ /* per-customer tools */ ]
}آپ اپنے سیشن کا سیاق (کون سا صارف براؤز کر رہا ہے، وہ کس صفحے پر ہیں) prompt میں شامل کر سکتے ہیں، اور ہر مرحلہ وار اجرا کے لیے ایجنٹس تبدیل کر سکتے ہیں۔
سیشنز کا مشاہدہ کریں
ویجٹ سیشنز
GET /v1/calls میں
direction="widget" کے ساتھ ظاہر ہوتے ہیں — فون کالز جیسا ہی ٹرانسکرپٹ، ریکارڈنگ، گریڈنگ، اور
بلنگ۔ صرف ویجٹ کے لیے ڈیش بورڈ بنانے کے لیے direction کے ذریعے فلٹر کریں۔