Open in

ฝังวิดเจ็ตบนเว็บ

เพิ่มเอเจนต์เสียงลงในเว็บไซต์การตลาดหรือเว็บไซต์สนับสนุนของคุณด้วยแท็กสคริปต์เพียงแท็กเดียว ผู้เข้าชมสามารถพูดคุยกับเอเจนต์ได้โดยตรงจากเบราว์เซอร์ โดยไม่ต้องใช้หมายเลขโทรศัพท์

วิดเจ็ตเว็บช่วยให้ผู้เข้าชมเว็บไซต์ของคุณเริ่มการสนทนาแบบคลิกเพื่อพูดคุย กับ AI เอเจนต์ โดยใช้ไมโครโฟนของเบราว์เซอร์ เป็น JavaScript / React SDK แยกต่างหากพร้อมข้อมูลอ้างอิง SDKของตนเอง — คู่มือนี้เน้นการตั้งค่าฝั่ง ThunderPhone ที่วิดเจ็ตต้องใช้

ข้อกำหนดเบื้องต้น

สร้างเอเจนต์
เอเจนต์ที่จะใช้พรอมป์ต์และเสียงในการทำงานของเซสชันวิดเจ็ต ตั้งค่า widget_enabled: true (ค่าเริ่มต้น)
กำหนดโหมดการกำหนดเส้นทาง
- mode="agent" — เอเจนต์แบบคงที่หนึ่งตัวต่อคีย์ ง่ายที่สุด
- mode="webhook" — เซิร์ฟเวอร์ของคุณเลือกเอเจนต์สำหรับผู้เข้าชมแต่ละรายผ่าน web.incoming webhook ใช้สำหรับ ผู้ใช้ที่ลงชื่อเข้าใช้ การทดสอบ A/B หรือการกำหนดเส้นทางตามแต่ละหน้า
ระบุโดเมนที่อนุญาต
ระบุทุก hostname ที่จะฝังวิดเจ็ต เบราว์เซอร์จะส่ง origin ของหน้า ไปพร้อมกับคำขอเซสชันแต่ละครั้ง ดังนั้นรายการนี้จะป้องกันไม่ให้คีย์ของคุณ ใช้งานได้เมื่อมีผู้คัดลอกไปใส่ในเว็บไซต์อื่น นี่ไม่ใช่การยืนยันตัวตน: สคริปต์ที่อยู่นอกเบราว์เซอร์สามารถส่ง header Origin ใดก็ได้ localhost จะไม่ได้รับอนุญาตโดยอัตโนมัติในระบบใช้งานจริง หากต้องการ ทดสอบในเครื่องกับ API สำหรับระบบใช้งานจริง ให้เพิ่ม localhost ลงใน รายการ
เลือกการแทนที่ค่าจากเบราว์เซอร์
กำหนดว่าหน้าของคุณสามารถส่งการตั้งค่าเซสชันใดได้บ้าง คีย์ใหม่จะไม่ยอมรับ การตั้งค่าใด ดู การแทนที่ค่าจากเบราว์เซอร์

สร้างคีย์แบบเผยแพร่ได้

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"]
  }'

การตอบกลับมี key ที่ขึ้นต้นด้วย pk_live_... คีย์แบบเผยแพร่ได้ เป็นข้อมูลสาธารณะโดยการออกแบบ — ปลอดภัยที่จะรวมไว้ในบันเดิลฟรอนต์เอนด์ของคุณ ดูข้อมูลอ้างอิงคีย์แบบเผยแพร่ได้สำหรับ ทุกฟิลด์

เพิ่มวิดเจ็ตลงในเว็บไซต์

มีตัวเลือกการผสานรวมสามแบบใน เอกสาร SDK ของวิดเจ็ต:

คอมโพเนนต์ React

<ThunderPhoneWidget publishableKey="pk_live_..." />

Hook แบบ Headless

useThunderPhone() สำหรับ UI แบบกำหนดเอง

แท็กสคริปต์ CDN

ThunderPhone.mount({...}) สำหรับเว็บไซต์ที่ไม่ใช้บันเดิลเลอร์

ทั้งสามแบบรับ publishableKey เดียวกัน และแสดงปุ่มไมโครโฟน พร้อมองค์ประกอบเสียงระหว่างการโทร

การกำหนดค่าแทนที่จากเบราว์เซอร์

วิดเจ็ตสามารถส่งการตั้งค่า 4 รายการต่อเซสชันจากหน้าเว็บได้:

การตั้งค่า	พร็อพของวิดเจ็ต	สิ่งที่เปลี่ยนแปลง
`context`	`context`	ข้อความจากหน้าเว็บ ซึ่งต่อท้ายในพรอมป์ต์ของเอเจนต์เพื่อใช้เป็นข้อมูลอ้างอิง
`variables`	ไม่มี (เฉพาะ `POST /v1/widget/session` แบบดิบ)	ค่าสำหรับตัวยึดตำแหน่ง `{{variable}}` ในพรอมป์ต์
`voice`	`voice`	เสียงของเอเจนต์สำหรับเซสชันนี้
`language`	`language`	ภาษาที่เซสชันเริ่มต้นใช้

คีย์ที่เผยแพร่ได้ของคุณเป็นสาธารณะ ดังนั้นทุกคนที่มีคีย์นี้จึงสามารถส่ง การตั้งค่าเหล่านี้ได้ รวมถึงจากสคริปต์ที่ปลอมแปลงโดเมนของคุณ การตั้งค่าแต่ละรายการจึง ปิดอยู่จนกว่าคุณจะอนุญาตบนคีย์: ทำเครื่องหมายที่ การแทนที่จากเบราว์เซอร์ เมื่อคุณสร้างหรือแก้ไข วิดเจ็ตในแดชบอร์ด หรือตั้งค่า allowed_overrides ผ่าน API คีย์ที่เผยแพร่ได้ อนุญาตเฉพาะสิ่งที่ หน้าเว็บของคุณส่งจริงเท่านั้น

คำขอเซสชันที่มีการตั้งค่าซึ่งคีย์ไม่อนุญาตจะล้มเหลวด้วย 400 และระบุชื่อการตั้งค่านั้น:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

การตรวจสอบนี้ใช้กับทั้งสองโหมด ในโหมดเว็บฮุก การตั้งค่าที่อนุญาตจะถูกส่งต่อไปยังเว็บฮุก web.incoming ของคุณด้วย (context จะมาถึงในชื่อ website_context) คีย์ที่สร้างก่อนมีการตั้งค่านี้อนุญาตทั้ง 4 รายการ ดังนั้นการฝังที่มีอยู่จึงยังทำงานต่อไปได้; ปิดสิ่งที่คุณไม่ได้ใช้

context ของวิดเจ็ตจะถูกตัดให้เหลือ 12,000 อักขระ (ประมาณ 3,400 โทเค็นของข้อความภาษาอังกฤษทั่วไป) และนับรวมใน ค่าบริการเพิ่มสำหรับขนาดพรอมป์ต์ เอเจนต์จะได้รับคำสั่งให้ถือว่านี่เป็นเนื้อหาของหน้าเว็บ ไม่ใช่คำสั่ง

Webhook โหมดวิดเจ็ต

เมื่อ mode="webhook" ThunderPhone จะเรียก webhook_url ของคุณทุกครั้ง ที่เริ่มเซสชัน พร้อมเพย์โหลด web.incoming ส่งคืนการกำหนดค่าเอเจนต์ ที่คุณต้องการให้ทำงานสำหรับผู้เข้าชมรายนั้น — โดยใช้ สคีมาการตอบกลับเดียวกับการโทร ทางโทรศัพท์:

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

คุณสามารถผสมบริบทจากเซสชันของคุณเอง (ลูกค้ารายใดกำลังเข้าชม และอยู่หน้าใด) ลงในพรอมป์ต์ และสลับเอเจนต์ตามการทยอยเปิดใช้ได้

ตรวจสอบเซสชัน

เซสชันวิดเจ็ตจะแสดงใน GET /v1/calls พร้อม direction="widget" — มีทรานสคริปต์ การบันทึก การให้คะแนน และ การเรียกเก็บเงินเช่นเดียวกับการโทรศัพท์ กรองตาม direction เพื่อสร้างแดชบอร์ดสำหรับวิดเจ็ตเท่านั้น

ขั้นตอนถัดไป

ข้อมูลอ้างอิง Widget SDK

รายละเอียดการผสานรวม React / hook / CDN

การกำหนดค่าต่อการโทรแบบไดนามิก

ใช้งานโฟลว์ mode="webhook" แบบครบวงจร

ข้อมูลอ้างอิงคีย์สำหรับเผยแพร่

ทุกฟิลด์ในทรัพยากรคีย์

API เซสชันไมโครโฟน

ข้ามวิดเจ็ต แล้วควบคุม LiveKit โดยตรงสำหรับ UI แบบกำหนดเอง

ฝังวิดเจ็ตบนเว็บ

ข้อกำหนดเบื้องต้น#

สร้างคีย์แบบเผยแพร่ได้#

เพิ่มวิดเจ็ตลงในเว็บไซต์#

การกำหนดค่าแทนที่จากเบราว์เซอร์#

Webhook โหมดวิดเจ็ต#

ตรวจสอบเซสชัน#

ขั้นตอนถัดไป#