वेब विजेट एम्बेड करें

एक ही स्क्रिप्ट टैग के साथ अपनी मार्केटिंग या सपोर्ट साइट पर वॉइस एजेंट जोड़ें — विज़िटर बिना किसी फोन नंबर के सीधे ब्राउज़र से उससे बात कर सकते हैं।

वेब विजेट आपके साइट विज़िटर्स को ब्राउज़र के माइक्रोफ़ोन का उपयोग करके AI एजेंट के साथ क्लिक-टू-टॉक बातचीत देता है। यह अपने SDK रेफ़रेंस के साथ एक अलग JavaScript / React SDK है — यह गाइड विजेट के लिए आवश्यक ThunderPhone-साइड सेटअप पर केंद्रित है।

पूर्वापेक्षाएँ#

1. एजेंट बनाएं

   वह एजेंट जिसका प्रॉम्प्ट और वॉइस विजेट सेशन चलाएंगे। सेट करें widget_enabled: true (डिफ़ॉल्ट)।

2. रूटिंग मोड तय करें
   • mode="agent" — हर की के लिए एक स्टैटिक एजेंट। सबसे सरल।
   • mode="webhook" — आपका सर्वर web.incoming वेबहुक के ज़रिए हर विज़िटर के लिए एजेंट चुनता है। इसका उपयोग लॉग-इन किए हुए यूज़र्स, A/B टेस्ट या प्रति-पेज रूटिंग के लिए करें।
3. अनुमत डोमेन सूचीबद्ध करें

   विजेट एम्बेड करने वाले हर होस्टनेम का नाम दें। ब्राउज़र हर सेशन रिक्वेस्ट के साथ पेज का ओरिजिन भेजते हैं, इसलिए यह सूची आपकी की को किसी अन्य साइट पर कॉपी किए जाने पर काम करने से रोकती है। यह ऑथेंटिकेशन नहीं है: ब्राउज़र के बाहर की कोई स्क्रिप्ट कोई भी Origin हेडर भेज सकती है। प्रोडक्शन में localhost अपने-आप अनुमत नहीं है; प्रोडक्शन API के विरुद्ध लोकली टेस्ट करने के लिए, सूची में localhost जोड़ें।

4. ब्राउज़र ओवरराइड चुनें

   तय करें कि आपका पेज कौन-सी सेशन सेटिंग्स भेज सकता है। नई कीज़ कोई भी स्वीकार नहीं करतीं; ब्राउज़र ओवरराइड देखें।

पब्लिशेबल की बनाएं#

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 डॉक्यूमेंटेशन में दिए गए हैं:

तीनों एक ही publishableKey स्वीकार करते हैं और माइक बटन के साथ इन-कॉल ऑडियो एलिमेंट रेंडर करते हैं।

ब्राउज़र ओवरराइड्स#

विजेट पेज से प्रति-सेशन चार सेटिंग भेज सकता है:

आपकी publishable key सार्वजनिक है, इसलिए जिसके पास भी यह है वह इन सेटिंग्स को भेज सकता है, जिसमें आपकी डोमेन का नकली रूप बनाने वाली स्क्रिप्ट से भेजना भी शामिल है। इसलिए हर सेटिंग तब तक बंद रहती है जब तक आप इसे key पर अनुमति नहीं देते: डैशबोर्ड में widget बनाते या संपादित करते समय ब्राउज़र ओवरराइड्स के अंतर्गत इसे चुनें, या Publishable keys API के माध्यम से allowed_overrides सेट करें। केवल वही अनुमति दें जो आपका पेज वास्तव में भेजता है।

ऐसा सेशन अनुरोध जिसमें ऐसी सेटिंग हो जिसकी 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 सभी चारों की अनुमति देती हैं, इसलिए मौजूदा एम्बेड काम करते रहते हैं; जिनका उपयोग नहीं करते, उन्हें बंद कर दें।

विजेट context को 12,000 कैरेक्टर तक सीमित किया जाता है (सामान्य अंग्रेज़ी टेक्स्ट के लगभग 3,400 टोकन) और यह प्रॉम्प्ट-आकार सरचार्ज में गिना जाता है। एजेंट को इसे निर्देशों के रूप में नहीं, बल्कि पेज कंटेंट के रूप में मानने के लिए कहा जाता है।

विजेट-मोड वेबहुक्स#

जब mode="webhook" हो, ThunderPhone हर सेशन शुरू होने पर web.incoming पेलोड के साथ आपके webhook_url को कॉल करता है। उस विज़िटर के लिए चलाने हेतु वांछित एजेंट कॉन्फ़िगरेशन लौटाएं — यह फ़ोन कॉल्स के समान रिस्पॉन्स स्कीमा का पालन करता है:

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

आप अपने सेशन का कॉन्टेक्स्ट (कौन-सा कस्टमर ब्राउज़ कर रहा है, वे किस पेज पर हैं) प्रॉम्प्ट में मिला सकते हैं और हर रोलआउट के लिए एजेंट बदल सकते हैं।

विजेट सेशन देखें#

विजेट सेशन GET /v1/calls में direction="widget" के साथ दिखते हैं — फोन कॉल्स जैसा ही ट्रांसक्रिप्ट, रिकॉर्डिंग, ग्रेडिंग और बिलिंग। केवल विजेट वाला डैशबोर्ड बनाने के लिए direction से फ़िल्टर करें।

अगले चरण#