ThunderPhone v3 اب لائیو ہے۔سیلف سرو، قیمت 2¢ فی منٹ سے شروع۔اعلان پڑھیں

Developer cookbook

ویب ویجیٹ ایمبیڈ کریں

ایک ہی اسکرپٹ ٹیگ کے ذریعے اپنی مارکیٹنگ یا سپورٹ سائٹ پر ایک وائس ایجنٹ شامل کریں — وزیٹرز فون نمبر کے بغیر براہِ راست براؤزر سے اس سے بات کر سکتے ہیں۔

ویب ویجٹ آپ کی سائٹ کے وزیٹرز کو براؤزر کے مائیکروفون کے ذریعے AI وائس ایجنٹ کے ساتھ کلک کر کے بات کرنے کی گفتگو فراہم کرتا ہے۔ یہ اپنا الگ JavaScript / React SDK ہے جس کا اپنا SDK حوالہ ہے — یہ گائیڈ ویجٹ کے لیے درکار ThunderPhone کی طرف کی سیٹ اپ پر مرکوز ہے۔

ضروری شرائط

  1. ایک ایجنٹ بنائیں

    وہ ایجنٹ جس کا prompt اور آواز وِجٹ سیشن چلائیں گے۔ widget_enabled: true (طے شدہ) سیٹ کریں۔

  2. روٹنگ موڈ طے کریں
    • mode="agent" — ہر کلید کے لیے ایک جامد ایجنٹ۔ سب سے آسان۔
    • mode="webhook" — آپ کا سرور ہر وزیٹر کے لیے ایجنٹ منتخب کرتا ہے web.incoming webhook کے ذریعے۔ اسے لاگ اِن صارفین، A/B ٹیسٹس، یا ہر صفحے کی روٹنگ کے لیے استعمال کریں۔
  3. اجازت یافتہ ڈومینز کی فہرست بنائیں

    ہر اُس ہوسٹ نیم کا نام درج کریں جو وِجٹ ایمبیڈ کرے گا۔ براؤزر ہر سیشن درخواست کے ساتھ صفحے کا ماخذ بھیجتے ہیں، اس لیے یہ فہرست آپ کی کلید کو اس وقت کام کرنے سے روکتی ہے جب کوئی اسے کسی دوسری سائٹ پر کاپی کرے۔ یہ تصدیقِ شناخت نہیں ہے: براؤزر سے باہر موجود ایک اسکرپٹ کوئی بھی Origin ہیڈر بھیج سکتی ہے۔ پروڈکشن میں localhost خودکار طور پر اجازت یافتہ نہیں ہے؛ پروڈکشن API کے خلاف مقامی طور پر ٹیسٹ کرنے کے لیے، localhost کو فہرست میں شامل کریں۔

  4. براؤزر اووررائیڈز منتخب کریں

    طے کریں کہ آپ کا صفحہ کن سیشن ترتیبات کو بھیج سکتا ہے۔ نئی کلیدیں کسی اووررائیڈ کو قبول نہیں کرتیں؛ براؤزر اووررائیڈز دیکھیں۔

شائع کرنے کے قابل کلید بنائیں

Static agent
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"]
  }'
Dynamic via webhook
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 دستاویزات میں انضمام کے تین اختیارات شامل ہیں:

تینوں ایک ہی publishableKey قبول کرتے ہیں اور مائیک بٹن کے ساتھ کال کے دوران آڈیو عنصر رینڈر کرتے ہیں۔

براؤزر اووررائیڈز

ویجٹ صفحے سے فی سیشن چار ترتیبات بھیج سکتا ہے:

ترتیبویجٹ propاس سے کیا تبدیل ہوتا ہے
contextcontextصفحے کا متن، بطور حوالہ ایجنٹ کے prompt میں شامل کیا جاتا ہے
variablesکوئی نہیں (صرف raw POST /v1/widget/session)prompt میں موجود {{variable}} پلیس ہولڈرز کی قدریں
voicevoiceاس سیشن کے لیے ایجنٹ کی آواز
languagelanguageوہ زبان جس میں سیشن شروع ہوتا ہے

آپ کی پبلش ایبل کلید عوامی ہے، اس لیے جس کے پاس بھی یہ ہو وہ یہ ترتیبات بھیج سکتا ہے، بشمول ایسے اسکرپٹ سے جو آپ کے ڈومین کی نقل کرتا ہو۔ لہٰذا ہر ترتیب اس وقت تک بند رہتی ہے جب تک آپ اسے کلید پر اجازت نہ دے دیں: ڈیش بورڈ میں ویجیٹ بناتے یا ترمیم کرتے وقت اسے براؤزر اووررائیڈز کے تحت منتخب کریں، یا 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 کے ذریعے فلٹر کریں۔


اگلے مراحل