OneBear Live Chat Widget — คู่มือตั้งค่าและการผสานระบบ

วิธีติดตั้งกล่องแช็ตสด OneBear บนเว็บไซต์ของคุณ เพื่อให้ข้อความจากผู้เยี่ยมชมเข้ามาที่คอนโซลเดียวกับช่องทางอื่น พร้อมใช้งาน AI agent, ตอบกลับอัตโนมัติ, การมอบหมายงาน, แท็ก และการติดตามผล เหมือนช่องทาง LINE หรือ Facebook ทุกอย่าง

วิดเจ็ตติดตั้งด้วย script tag บรรทัดเดียว ไม่ต้องทำ OAuth และไม่ต้องเขียนโค้ดฝั่งเซิร์ฟเวอร์สำหรับการตั้งค่าพื้นฐาน มีเพียง 2 ส่วนที่เป็นทางเลือกเสริม (โหมดระบุตัวตน และการควบคุมด้วยโค้ด) ที่ต้องเขียนโค้ดเล็กน้อย

เอกสารที่เกี่ยวข้อง: api-channel-setup.th.md — สำหรับกรณีที่ต้องการเชื่อมระบบภายนอกผ่าน REST API แทนการฝังวิดเจ็ต

1. หลักการทำงาน

เว็บไซต์ของคุณ
  │
  │  <script> …/widget/loader.js       ← โค้ดที่คุณวาง
  ▼
ปุ่มลอย (launcher)  ──คลิก──▶  แผงแช็ตในรูปแบบ iframe (โฮสต์โดย OneBear)
  │
  │  POST /api/v1/widget/{publicKey}/session      (เริ่มเซสชัน)
  │  WebSocket /hubs/widget                       (ส่ง + รับข้อความ)
  ▼
OneBear API  ──▶  คอนโซลเจ้าหน้าที่ (สร้างห้องใหม่ หรือใช้ห้องเดิม)
                    AI agent / ตอบกลับอัตโนมัติ / มอบหมายงาน / แท็ก / ติดตามผล
                       │
                       └──▶ คำตอบจากเจ้าหน้าที่หรือ AI ส่งกลับเข้าแผงแช็ตแบบเรียลไทม์

ประเด็นสำคัญ:

หน้าจอแช็ตทำงานอยู่ใน iframe ที่โฮสต์โดย OneBear — CSS ของเว็บคุณจึงทำให้หน้าตาเพี้ยนไม่ได้ และ JavaScript ของเว็บคุณก็อ่านบทสนทนาไม่ได้

สิ่งที่รันบนหน้าเว็บคุณจริง ๆ มีแค่ loader.js ตัวเล็ก ๆ ทำหน้าที่วาดปุ่มลอย ใส่สีธีม และเปิด/ปิด iframe

ข้อความไหลผ่าน pipeline เดียวกับทุกช่องทาง วงจรห้องแช็ต (ใหม่ → กำลังดำเนินการ → ปิดงาน), AI, ตอบกลับอัตโนมัติ, แท็ก และการติดตามผล ใช้งานได้เลยโดยไม่ต้องตั้งค่าเพิ่ม

ผู้เยี่ยมชมเป็นได้ทั้งแบบ ไม่ระบุตัวตน (ค่าเริ่มต้น) และ ระบุตัวตน (คุณยืนยันว่าเป็นใครด้วย HMAC — ดูหัวข้อ 6)

2. สร้างวิดเจ็ตในคอนโซล

เข้าสู่ระบบ OneBear → ตั้งค่า → การเชื่อมต่อ (Integrations)

กด เชื่อมต่อ ที่ Live Chat Widget

กรอกการตั้งค่า:

ช่อง	ทำหน้าที่อะไร
ชื่อวิดเจ็ต	ชื่อสำหรับใช้ภายใน แสดงในกล่องข้อความให้เจ้าหน้าที่รู้ว่าผู้เยี่ยมชมมาจากเว็บไหน (จำเป็น)
สีธีม	สี hex ของปุ่มลอยและองค์ประกอบเน้นในแผงแช็ต ค่าเริ่มต้น `#41C3A8`
ข้อความต้อนรับ	ข้อความแรกที่ผู้เยี่ยมชมเห็นเมื่อเปิดแผงแช็ต เว้นว่างได้ถ้าไม่ต้องการ
โดเมนเว็บไซต์ที่อนุญาต	รายการ origin ที่อนุญาตให้โหลดวิดเจ็ต คั่นด้วยจุลภาค เว้นว่าง = อนุญาตทุกเว็บ ดูหัวข้อ 5 — จุดพลาดอันดับ 1
ให้กรอกชื่อและอีเมลก่อนเริ่มแช็ต	แสดงฟอร์มสั้น ๆ ก่อนผู้เยี่ยมชมพิมพ์ได้ ค่าเริ่มต้นคือปิด ปรับได้ว่าจะถามฟิลด์ไหนหลังสร้างเสร็จ (ดูด้านล่าง)
ข้อความนอกเวลาทำการ	ข้อความที่แสดงเมื่อผู้เยี่ยมชมเปิดแช็ตนอกเวลาทำการของร้าน เว้นว่างได้ (จะใช้ข้อความมาตรฐานแทน)

กด สร้างวิดเจ็ต

หลังสร้างเสร็จ ที่หน้าตั้งค่าวิดเจ็ตจะมีเพิ่มอีก 4 ส่วนที่ตั้งตอนสร้างไม่ได้:

โหมดระบุตัวตน — แสดง/หมุนเวียนรหัสลับตัวตน (หัวข้อ 6)

ชื่อที่แสดงเมื่อ AI ตอบ และ รูปโปรไฟล์ของบอท — ชื่อและรูปที่ลูกค้าเห็นบนข้อความที่ AI ตอบ เว้นว่างทั้งคู่ = ข้อความจาก AI จะไม่แสดงชื่อ ส่วนข้อความที่เจ้าหน้าที่พิมพ์เองจะแสดงชื่อและรูปของเจ้าหน้าที่คนนั้นเสมอ (หัวข้อ 4)

ฟิลด์ในฟอร์มก่อนเริ่มแช็ต — ตั้ง ชื่อ และ อีเมล เป็น จำเป็น / ไม่บังคับ / ซ่อน และเพิ่ม custom field ของคุณได้สูงสุด 8 ฟิลด์ เรียงลำดับตามที่ต้องการถาม และเลือกได้ว่าฟิลด์ไหนต้องกรอก

custom field ที่อนุญาตให้หน้าเว็บส่งได้ — เลือกว่าฟิลด์ไหนที่หน้าเว็บของคุณส่งค่าเข้ามาได้ ค่าเริ่มต้นคือไม่อนุญาตเลย (หัวข้อ 10)

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

3. วางโค้ดฝัง

เปิด ตั้งค่า → การเชื่อมต่อ → วิดเจ็ตของคุณ ส่วน โค้ดฝัง จะแสดงโค้ดที่ใส่ publicKey ของคุณมาให้เรียบร้อยแล้ว:

วางไว้ ก่อน </body> ในทุกหน้าที่ต้องการให้ปุ่มแช็ตแสดง

ให้คัดลอกโค้ดจากคอนโซล ไม่ใช่จากเอกสารนี้ เพราะคอนโซลจะใส่ host ที่ถูกต้องของ environment คุณมาให้

publicKey ไม่ใช่ความลับ ออกแบบให้มองเห็นได้ใน source ของหน้าเว็บ ดังนั้นสิ่งที่ป้องกันวิดเจ็ตจริง ๆ คือรายการโดเมนที่อนุญาต (หัวข้อ 5)

โหลดแบบ async จึงไม่บล็อกการแสดงผลหน้าเว็บ

ตำแหน่งที่นิยมวาง: footer template ของเว็บ (WordPress footer, Shopify theme.liquid, Next.js _document/root layout) หรือ Custom HTML tag ใน Google Tag Manager

วางเสร็จแล้วรีโหลดหน้าเว็บ ปุ่มจะขึ้นมุมขวาล่าง ทดลองส่งข้อความและตรวจสอบว่าเข้ามาในกล่องข้อความ OneBear

4. สิ่งที่ผู้เยี่ยมชมเห็น

แผงแช็ตมี 3 แท็บ:

แท็บ	เนื้อหา
ข้อความ	บทสนทนาสด พร้อมข้อความต้อนรับและปุ่มแนบไฟล์
บทความ	บทความ Help Center ที่เผยแพร่แล้ว เรียกดูตามหมวดหมู่ ค้นหาด้วยคำค้น และกดให้คะแนนบทความได้
ค้นหา	ถาม AI — พิมพ์คำถามแล้วได้คำตอบที่อ้างอิงจากบทความของคุณ พร้อมลิงก์บทความต้นทาง

แท็บบทความและถาม AI ดึงข้อมูลจาก Help Center ของบริษัทเดียวกัน ถ้ายังไม่เผยแพร่บทความไว้ แท็บทั้งสองจะว่างเปล่า — เผยแพร่บทความที่ Help Center → Studio เพื่อให้มีเนื้อหา (แท็บถาม AI ใช้เครดิต AI — ดูหัวข้อ 10)

สิ่งที่ผู้เยี่ยมชมเห็นในแท็บข้อความ:

สถานะการส่ง ต่อข้อความของตัวเอง (กำลังส่ง / ส่งแล้ว / ส่งไม่สำเร็จ) และกดส่งซ้ำได้เมื่อล้มเหลว

จุดสามจุด "กำลังพิมพ์" เมื่อเจ้าหน้าที่กำลังพิมพ์ตอบ และฝั่งเจ้าหน้าที่ก็เห็นเมื่อผู้เยี่ยมชมพิมพ์

ตัวเลขแจ้งเตือนบนปุ่มลอย พร้อมเสียงเตือน เมื่อมีคำตอบเข้ามาขณะแผงแช็ตปิดอยู่ (ปิดเสียงได้ — หัวข้อ 7)

แถบแจ้งนอกเวลาทำการ เมื่อร้านปิดตามเวลาทำการที่ตั้งไว้ (ตั้งค่า → ข้อมูลร้าน) พร้อมข้อความนอกเวลาที่คุณกำหนด และจะขอ อีเมล เพื่อให้ตอบกลับได้

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

การ์ดสินค้าแบบเลื่อนได้ (carousel) ถ้า AI หรือกฎอัตโนมัติส่งมา กดปุ่มบนการ์ดแล้วตัวเลือกจะถูกส่งเป็นข้อความของผู้เยี่ยมชม

ตอบกลับแบบอ้างอิงข้อความ (quote) ผู้เยี่ยมชมเลือกอ้างอิงข้อความไหนก็ได้ในเธรด ข้อความที่อ้างอิงจะแสดงเป็นบล็อกเหนือข้อความของตัวเอง และกดที่บล็อกนั้นเพื่อเลื่อนกลับไปยังข้อความต้นทางได้ถ้ายังโหลดอยู่

โหลดประวัติเก่าเมื่อเลื่อนขึ้นบนสุด เปิดแผงแช็ตครั้งแรกโหลด 50 ข้อความล่าสุด และโหลดเพิ่มอีก 50 ทุกครั้งที่เลื่อนขึ้นถึงบนสุด (หัวข้อ 8)

แบบประเมินความพึงพอใจในแผงแช็ต เมื่อปิดงานบทสนทนาและเปิดใช้ CSAT ไว้ (ตั้งค่า → ความพึงพอใจ) ผู้เยี่ยมชมให้คะแนนในแผงแช็ตได้เลย ไม่ต้องกดลิงก์ออกไปหน้าอื่น

เปิดวิดีโอและไฟล์ที่เจ้าหน้าที่ส่ง วิดีโอเล่นในแผงแช็ตได้ ไฟล์อื่นดาวน์โหลด

ข้อความของตัวเองขึ้นครบทุกแผงที่เปิดอยู่ เปิดสองแท็บ หรือ (เมื่อระบุตัวตนแล้ว) เปิดทั้งมือถือและคอมพร้อมกัน อีกฝั่งก็เห็นข้อความที่เพิ่งส่งจากอีกเครื่อง

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

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

ลูกค้าเห็นว่าใครเป็นคนตอบ ข้อความที่เจ้าหน้าที่พิมพ์เองจะแสดงชื่อและรูปโปรไฟล์ของเจ้าหน้าที่คนนั้น (ถ้าไม่มีรูปจะเป็นอักษรย่อ) ข้อความที่ AI ตอบจะแสดง ชื่อและรูปของบอท ที่ตั้งไว้ในวิดเจ็ต (หัวข้อ 2) ถ้าเว้นว่างทั้งคู่ ข้อความจาก AI จะแสดงเพียงไอคอนแชทกลาง ๆ ไม่มีชื่อ ส่วนข้อความระบบ (ข้อความต้อนรับ, ประกาศ) ไม่มีรูปโปรไฟล์เลย

การแนบไฟล์ ผู้เยี่ยมชมแนบไฟล์จากช่องพิมพ์ได้ ครั้งละ 1 ไฟล์:

ประเภท	ชนิดที่อนุญาต
รูปภาพ	PNG, JPEG, GIF, WebP และ HEIC/HEIF ซึ่งรับได้แต่จะไปในรูปไฟล์ให้ดาวน์โหลด เพราะมีแต่ Safari ที่แสดงผลไฟล์ชนิดนี้ได้
เอกสาร	PDF, TXT, CSV, Word (`.doc`, `.docx`), Excel (`.xls`, `.xlsx`, `.xlsm`), PowerPoint (`.ppt`, `.pptx`)
วิดีโอ	MP4, MOV, WebM
เสียง	MP3, M4A, AAC, OGG, WAV

ขนาดไม่เกิน 25 MB ต่อไฟล์

ตัวที่ใช้ตัดสินคือ นามสกุลไฟล์ ไม่ใช่ content type ที่เบราว์เซอร์แจ้งมา เพราะไฟล์ .csv ตัวเดียวกันมาถึงเราเป็น text/csv, application/vnd.ms-excel หรือค่าว่าง แล้วแต่ระบบปฏิบัติการของผู้เยี่ยมชม นามสกุลที่ปลายทางอาจถูกเปิดเป็นเนื้อหาที่รันได้ (.html, .htm, .svg, .xhtml) และไฟล์สคริปต์/โปรแกรมทุกชนิดถูกปฏิเสธ

นอกเหนือจากนี้จะถูกปฏิเสธและแสดงข้อผิดพลาดในแผงแช็ต ไฟล์ที่อัปโหลดนับรวมในโควตาพื้นที่จัดเก็บของบริษัท

5. โดเมนเว็บไซต์ที่อนุญาต (ต้องอ่าน)

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

กฎ:

เว้นว่าง = ทุกเว็บฝังวิดเจ็ตได้ เหมาะกับช่วงทดสอบ แต่ควรจำกัดก่อนใช้งานจริง

ต้องใส่เป็น origin เต็ม มี scheme และไม่มี path:

✅ https://example.com

✅ https://shop.example.com

❌ example.com (ไม่มี scheme)

❌ https://example.com/contact (มี path)

ใช้ wildcard ไม่ได้ https://*.example.com ไม่ทำงาน — ต้องใส่ทุก subdomain ที่ใช้จริง

ลงท้ายด้วย / ได้ (https://example.com/ ตรงกัน) และไม่สนใจตัวพิมพ์เล็กใหญ่

http://localhost:3000 และ http://127.0.0.1:5173 ก็เป็น origin ปกติ — ถ้าทดสอบบนเครื่องต้องใส่เพิ่มเอง

หมายเหตุด้านความปลอดภัย: origin ถูกรายงานมาจาก loader ที่รันอยู่บนหน้าเว็บของคุณ จึงเป็น ตัวกรองแบบ best-effort ไม่ใช่กลไกยืนยันตัวตน มันช่วยกันการฝังวิดเจ็ตผิดเว็บโดยไม่ตั้งใจหรือจากการคัดลอกโค้ดไปมั่ว ๆ แต่กันผู้ไม่ประสงค์ดีที่สร้าง request ขึ้นมาเองไม่ได้ ถ้าต้องการรู้ว่า ใคร คือผู้เยี่ยมชมจริง ๆ ให้ใช้โหมดระบุตัวตน (หัวข้อ 6)

ถ้าปุ่มขึ้นแต่แผงแช็ตเชื่อมต่อไม่ได้ ให้ตรวจรายการนี้ก่อนเป็นอันดับแรก

6. โหมดระบุตัวตน (ผู้เยี่ยมชมที่ยืนยันตัวตนแล้ว)

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

6.1 ดูรหัสลับตัวตน

ตั้งค่า → การเชื่อมต่อ → วิดเจ็ตของคุณ → โหมดระบุตัวตน → แสดงรหัสลับ

รหัสลับนี้ ไม่ใช่ publicKey และต้องไม่ถูกส่งไปถึงเบราว์เซอร์เด็ดขาด

หมุนเวียนรหัสลับ ยกเลิกค่าเดิมทันที หน้าเว็บที่ยังส่ง hash ที่คำนวณจากรหัสเก่าจะเริ่มเซสชันไม่ได้ — ให้ deploy รหัสใหม่ก่อนแล้วจึงหมุนเวียน หรือยอมรับว่าจะมีช่วงใช้งานไม่ได้สั้น ๆ

ทั้งการแสดงและการหมุนเวียนต้องมีสิทธิ์ SettingsChannelsManage

6.2 คำนวณ `userHash` บนเซิร์ฟเวอร์ของคุณ

userHash = hex( HMAC-SHA256( key = identitySecret, message = userId ) )

เซ็นเฉพาะ userId เท่านั้น — name และ email ไม่รวมอยู่ใน hash ดังนั้นเปลี่ยนชื่อที่แสดงได้โดยไม่ต้องคำนวณใหม่

Node.js

PHP

Python

ใช้ hex ตัวพิมพ์เล็กหรือใหญ่ก็ได้ เซิร์ฟเวอร์อ่านโดยไม่สนใจตัวพิมพ์

6.3 ส่งค่าให้วิดเจ็ต

เรนเดอร์ hash ลงในหน้าเว็บ จากฝั่งเซิร์ฟเวอร์ (หรือดึงจาก endpoint ที่ต้องยืนยันตัวตนของคุณเอง):

สิ่งที่เปลี่ยนไปในโหมดระบุตัวตน:

ประวัติการสนทนาผูกกับ ตัวบุคคล ไม่ใช่เบราว์เซอร์ — คนเดิมเห็นประวัติเดิมแม้เปลี่ยนเครื่องหรือล้างคุกกี้

ข้ามฟอร์มก่อนแช็ต (เพราะ OneBear มีชื่อและอีเมลอยู่แล้ว)

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

ถ้าส่ง avatarUrl มาด้วย เจ้าหน้าที่จะเห็นรูปโปรไฟล์จริงของผู้ใช้ในห้องแช็ต แทนตัวอักษรย่อ

name email phone และ avatarUrl ใส่หรือไม่ใส่ก็ได้ ส่วน email กับ phone จะถูกเขียนลงช่องอีเมล/เบอร์โทรของลูกค้า
เฉพาะเมื่อช่องนั้นยังว่าง ถ้าเจ้าหน้าที่แก้ไว้ด้วยมือแล้ว ค่าที่เจ้าหน้าที่กรอกจะไม่ถูกทับ แนะนำให้ส่งข้อมูลติดต่อทางนี้
แทนการส่งผ่าน customFields เพราะ custom field เป็นค่าคนละช่อง — ตัวกรองในรายการลูกค้า การตรวจข้อมูลซ้ำ และการค้นหา
จะไม่มองว่าเป็นอีเมลหรือเบอร์โทร

avatarUrl ต้องเป็น URL แบบเต็มที่ขึ้นต้นด้วย https: และยาวไม่เกิน 2048 ตัวอักษร ถ้าเป็น path แบบสัมพัทธ์
http: (หน้าเจ้าหน้าที่เป็น https จะบล็อกเป็น mixed content) data: URI หรือแปลงเป็น URL ไม่ได้ ระบบจะ ตัดทิ้งเงียบ ๆ
โดยรูปเดิมที่มีอยู่แล้วยังคงอยู่ — รูปที่ผิดรูปแบบจะไม่ทำให้เซสชันล้มเหลว

มีเพียง userId เท่านั้นที่ถูกครอบด้วย hash ส่วน name email phone และ avatarUrl ส่งมาแบบไม่ได้เซ็น จึงควรถือว่าเป็น
ความสะดวกสำหรับผู้ใช้ที่ล็อกอินบนเว็บของคุณเอง ไม่ใช่หลักฐานยืนยันตัวตน

กรณีที่ล้มเหลว:

hash ผิดหรือเก่า → INVALID_IDENTITY_HASH ปฏิเสธเซสชัน (ไม่ ถอยกลับไปเป็นแบบไม่ระบุตัวตนเงียบ ๆ)

ส่ง identify มาแต่ยังไม่ได้ตั้งรหัสลับตัวตน → IDENTITY_SECRET_NOT_CONFIGURED

ห้าม คำนวณ hash ด้วย JavaScript ในเบราว์เซอร์ เพราะเท่ากับเปิดเผยรหัสลับ และใครก็สวมรอยเป็นใครก็ได้

7. การควบคุมด้วยโค้ด

ตัวเลือกเพิ่มเติมบน window.OneBearWidget:

ตัวเลือก	ชนิด	ค่าเริ่มต้น	ทำหน้าที่อะไร
`hideLauncher`	`boolean`	`false`	ซ่อนปุ่มลอย ใช้เมื่อคุณต้องการเปิดแผงแช็ตจาก UI ของตัวเอง
`autoOpen`	`boolean`	`false`	เปิดแผงแช็ตทันทีที่ loader ทำงาน
`position`	`'left' \| 'right'`	`'right'`	ปุ่มลอยและแผงแช็ตยึดกับด้านไหนของหน้าจอ
`sound`	`boolean`	`true`	เสียงแจ้งเตือนเมื่อมีข้อความตอบกลับขณะแผงแช็ตปิดอยู่ ตั้ง `false` เพื่อปิดเสียง
`customFields`	`Record<string, string>`	—	ส่งค่า custom field ของบริษัทเข้าระเบียนลูกค้า ใช้ได้เฉพาะโหมดระบุตัวตน + ฟิลด์ที่เปิดสิทธิ์ไว้ (หัวข้อ 10)

เมื่อ loader ทำงานแล้ว จะกำหนดฟังก์ชัน 3 ตัวให้เรียกใช้ได้:

สำคัญเมื่อเว็บคุณมีระบบล็อกอิน: เรียก reset() ตอนผู้ใช้ล็อกเอาต์ ไม่งั้นคนถัดไปที่ใช้เบราว์เซอร์เดียวกันจะเห็นบทสนทนาของคนก่อน reset() จะถอด iframe ออกและล้าง visitor token ทิ้ง

รูปแบบที่ใช้บ่อย — เมนู "ติดต่อฝ่ายสนับสนุน" ของคุณเอง โดยไม่มีปุ่มลอย:

open และ close ถูกกำหนดแบบ asynchronous (หลัง loader.js ดาวน์โหลดเสร็จ) จึงควรกันด้วย && หรือซ่อนปุ่มไว้จนกว่า loader จะพร้อม เผื่อกรณีผู้ใช้กดภายในไม่กี่ร้อยมิลลิวินาทีแรก

8. ความต่อเนื่องของบทสนทนา

ผู้เยี่ยมชมไม่ระบุตัวตน loader เก็บ visitor token ไว้ใน localStorage ของหน้าเว็บคุณ เบราว์เซอร์เดิมที่กลับมาภายหลังจะสนทนาต่อในห้องเดิม เห็นประวัติเดิม และข้ามฟอร์มก่อนแช็ต ถ้าล้างข้อมูลเว็บไซต์ เปลี่ยนเบราว์เซอร์ หรือใช้โหมดส่วนตัว จะเริ่มบทสนทนาใหม่ (token เก็บไว้ที่ หน้าเว็บของคุณ ไม่ใช่ใน iframe เพราะเบราว์เซอร์สมัยใหม่แยกส่วนหรือบล็อกพื้นที่จัดเก็บของ iframe จากโดเมนอื่น)

ผู้เยี่ยมชมที่ระบุตัวตน ความต่อเนื่องผูกกับ userId ของคุณ ประวัติจึงติดตามตัวบุคคลข้ามอุปกรณ์

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

ประวัติที่แสดง แผงแช็ตโหลดข้อความล่าสุด 50 รายการเมื่อเปิด และโหลดเพิ่มอีก 50 ทุกครั้งที่ผู้เยี่ยมชมเลื่อนขึ้นถึงบนสุด ภายในช่วงระยะเวลาเก็บประวัติที่ตั้งไว้ ข้อความที่เจ้าหน้าที่ส่งไม่สำเร็จจะไม่ถูกนับรวม (หัวข้อ 4)

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

9. AI agent และการส่งต่อให้มนุษย์ (handoff)

วิดเจ็ตเป็นช่องทางปกติ ดังนั้น AI agent ทำงานเหมือนกับบน LINE หรือ Facebook

เปิด AI สำหรับวิดเจ็ต: ตั้งค่า → AI → ช่องทาง แล้วเปิดสวิตช์ที่วิดเจ็ตของคุณ (สวิตช์หลักของ AI ต้องเปิดอยู่ด้วย) เมื่อเปิดแล้ว AI จะตอบผู้เยี่ยมชม และส่งต่อให้มนุษย์เมื่อ AI ประเมินว่าควรส่งต่อ หรือเมื่อเจ้าหน้าที่เข้ามารับเองจากคอนโซล

การส่งต่อเกิดขึ้นภายในระบบทั้งหมด — คุณไม่ต้องทำอะไรเพิ่ม นี่คือความต่างสำคัญจาก API Channel:

	API Channel	Live Chat Widget
หน้าจอแช็ตอยู่ที่ไหน	แอปของคุณ	iframe ของ OneBear
ใครส่งคำตอบถึงผู้ใช้ปลายทาง	คุณ ผ่าน outbound webhook	OneBear ส่งเข้าแผงแช็ตโดยตรง
การส่งต่อจาก AI ไปมนุษย์	ยิง webhook event `handoff` เพื่อให้ คุณ หยุด bot ของตัวเอง	จัดการภายใน OneBear: AI หยุดตอบ ห้องถูกมอบหมายให้เจ้าหน้าที่ ผู้เยี่ยมชมแช็ตต่อในแผงเดิม
งานที่คุณต้องทำ	สร้าง webhook endpoint, ตรวจ signature, หยุด bot	ไม่มี

จากมุมของผู้เยี่ยมชม ตอนส่งต่อไม่มีอะไรเกิดขึ้นให้เห็น — คำตอบเปลี่ยนจาก AI เป็นคนเท่านั้น ไม่มี webhook ไม่มี conversationId ไม่ต้องตรวจ signature

กฎตอบกลับอัตโนมัติ, ข้อความต้อนรับ, แท็ก, การมอบหมายอัตโนมัติ และการตั้งเวลาติดตามผล ใช้กับห้องของวิดเจ็ตเหมือนกับที่ตั้งไว้สำหรับช่องทางอื่นทุกประการ

10. ข้อจำกัด และสิ่งที่วิดเจ็ตยังทำไม่ได้

การจำกัดอัตราการเรียก (rate limit) โควตาแยกตามวิดเจ็ต (หรือตามเซสชันผู้เยี่ยมชม) ทราฟฟิกของเว็บหนึ่งจึงไม่กระทบเว็บอื่น:

รายการ	ขอบเขต
ดึงค่าหน้าตาปุ่มลอย (ต่อการโหลดหน้าเว็บ)	600 ครั้ง/นาที ต่อวิดเจ็ต
เริ่มเซสชัน (ต่อการเปิดแผงแช็ต)	60 ครั้ง/นาที ต่อวิดเจ็ต
ส่งข้อความ	20 ครั้ง/นาที ต่อผู้เยี่ยมชม · 300 ครั้ง/นาที ต่อวิดเจ็ต
เรียกดู/ค้นหาบทความช่วยเหลือ	60 ครั้ง/นาที ต่อเซสชันผู้เยี่ยมชม
อัปโหลดไฟล์แนบ	20 ครั้ง/นาที ต่อเซสชันผู้เยี่ยมชม
ถาม AI ในแท็บช่วยเหลือ	10 ครั้ง/นาที ต่อผู้เยี่ยมชม · 60 ครั้ง/นาที ต่อบริษัท

เมื่อเกินจะได้ HTTP 429 พร้อม header Retry-After (กรณีส่งข้อความจะขึ้นข้อผิดพลาดในแผงแช็ต แล้วลองใหม่ได้ในอีกไม่นาน) ส่วนค่าหน้าตาถูก cache ไว้ 60 วินาที การเข้าชมปกติจึงไม่ต้องเรียกซ้ำทุกหน้า — ผลข้างเคียงคือการเปลี่ยนสีธีมจะไปถึงผู้เยี่ยมชมภายในประมาณหนึ่งนาที ไม่ใช่ทันที

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

ข้อมูลผู้เยี่ยมชมที่วิดเจ็ตส่งได้:

ข้อมูล	ส่งผ่านอะไร
`userId`	`identify` (โหมดระบุตัวตนเท่านั้น)
ชื่อ	`identify` หรือฟอร์มก่อนแช็ต
อีเมล	`identify` หรือฟอร์มก่อนแช็ต
เบอร์โทร	`identify`
custom field ของบริษัทคุณ	`customFields` (หัวข้อ 7) — ต้องอยู่ในโหมดระบุตัวตน และต้องเปิดสิทธิ์รายฟิลด์
บริบทการเข้าชม	เก็บอัตโนมัติ ไม่ต้องตั้งค่า (ดูด้านล่าง)

บริบทการเข้าชม ถูกเก็บจากหน้าเว็บของคุณโดยอัตโนมัติและแสดงให้เจ้าหน้าที่เห็นในข้อมูลลูกค้า ได้แก่
pageUrl, pageTitle, referrer, language, timezone, screen, viewport, userAgent โดย query
parameter ที่เข้าข่ายอ่อนไหว (เช่น token, รหัสผ่าน) จะถูกแทนด้วย … ก่อนส่ง และทุกค่าถูกตัดความยาว

custom field จากหน้าเว็บ ส่งค่าอย่างเลขที่ออร์เดอร์, แพ็กเกจ หรือประเภทบัญชี เข้าไปในระเบียนลูกค้าได้ผ่าน
customFields แต่มีด่าน 2 ชั้นโดยเจตนา: (1) ใช้ได้เฉพาะเซสชันที่ ระบุตัวตนแล้ว เพราะผู้เยี่ยมชมที่ไม่ระบุตัวตน
อ้างเป็นใครก็ได้ และ (2) ต้องเลือกเปิดฟิลด์ที่อนุญาตไว้ที่ ตั้งค่า → การเชื่อมต่อ → วิดเจ็ตของคุณ ค่าเริ่มต้นคือ
ไม่อนุญาตฟิลด์ใดเลย ฟิลด์ที่ไม่ได้เปิดสิทธิ์จะถูกละเว้นเงียบ ๆ ไม่บันทึก

ข้อจำกัดอื่นในปัจจุบัน:

ฟอร์มก่อนแช็ตถามชื่อ + อีเมล (แต่ละช่องตั้งเป็น จำเป็น / ไม่บังคับ / ซ่อน ได้) และเพิ่ม custom field ของคุณได้สูงสุด 8 ฟิลด์ (หัวข้อ 2) แต่เก็บเบอร์โทรลงช่อง โทรศัพท์ ของลูกค้าไม่ได้ — เบอร์ที่กรอกใน custom field ยังเป็น custom field ซึ่งตัวกรองในลิสต์ การตรวจข้อมูลซ้ำ และการค้นหา ไม่ได้อ่านเป็นเบอร์โทร ถ้าต้องการลงช่องจริงให้ส่งผ่าน identify (หัวข้อ 6)

ปรับแต่งหน้าตาแผงแช็ตได้เฉพาะสีธีม

ไฟล์แนบไม่เกิน 25 MB ต่อไฟล์ แนบได้ครั้งละ 1 ไฟล์ และจำกัดนามสกุลตามรายการในหัวข้อ 4

ข้อความมีความยาวสูงสุดที่เซิร์ฟเวอร์บังคับ ข้อความยาวเกินจะถูกปฏิเสธ ไม่ใช่ตัดให้

ปุ่มตอบด่วน (quick reply) ใช้กับวิดเจ็ตไม่ได้ ถ้ากฎตอบกลับอัตโนมัติหรือ AI แนบปุ่มมา วิดเจ็ตจะไม่แสดง (การ์ดแบบ carousel แสดงได้)

ไม่มี JavaScript event API ฝั่งหน้าเว็บ — ดักเหตุการณ์ "ได้รับข้อความ" หรือ "เริ่มบทสนทนา" ไม่ได้ มีแค่ open(), close() และ reset() (หัวข้อ 7)

11. ความปลอดภัย

publicKey เป็นข้อมูลเปิด ออกแบบให้อ่านได้จาก source ของหน้าเว็บ ทำหน้าที่ระบุว่าเป็นวิดเจ็ตตัวไหน และไม่ให้สิทธิ์อะไรนอกจากเริ่มเซสชันผู้เยี่ยมชม

รหัสลับตัวตนเป็นข้อมูลรับรอง (credential) ใช้ฝั่งเซิร์ฟเวอร์เท่านั้น เก็บใน environment variable หรือ secret manager ห้ามอยู่ในโค้ดฝั่งเบราว์เซอร์ ห้ามคอมมิตลง repo

รายการโดเมนที่อนุญาตเป็นแค่ราวกันตก ไม่ใช่การยืนยันตัวตน (หัวข้อ 5) ถ้าตัวตนสำคัญ ให้ใช้ร่วมกับโหมดระบุตัวตน

แผงแช็ตถูกแยกไว้ใน iframe บน origin ของ OneBear สคริปต์ของเว็บคุณอ่านบทสนทนาไม่ได้ และในทางกลับกันก็เช่นกัน

ไฟล์อัปโหลดถูกจำกัดชนิดและขนาด (หัวข้อ 4) และส่งกลับผ่าน endpoint สื่อที่ต้องยืนยันตัวตน ไม่ใช่ URL สาธารณะ

การหมุนเวียนรหัสลับตัวตนมีผลทันที ถ้าต้องการไม่ให้ระบบสะดุด ให้ deploy รหัสใหม่ไปที่เซิร์ฟเวอร์คุณก่อน

ทุกเซสชันวิดเจ็ตผูกกับบริษัทเดียวและช่องทางเดียว โทเค็นเซสชันของวิดเจ็ต A อ่านบทสนทนาของวิดเจ็ต B ไม่ได้เลย

12. แก้ปัญหาเบื้องต้น

อาการ	สาเหตุที่เป็นไปได้
ไม่มีปุ่มขึ้นเลย	ยังไม่ได้วางโค้ดในหน้านั้น หรือมี error ใน console — เปิด DevTools → Console หา `[OneBear widget] window.OneBearWidget.publicKey is required` และตรวจว่า `loader.js` ตอบ 200 ในแท็บ Network
ปุ่มขึ้น แต่แผงแช็ตแสดงข้อผิดพลาดการเชื่อมต่อ	origin ไม่อยู่ใน โดเมนเว็บไซต์ที่อนุญาต (หัวข้อ 5) ตรวจให้ตรงทั้ง scheme และพอร์ต
แผงแช็ตเปิดได้ แต่ไม่มีข้อความเข้าคอนโซล	วิดเจ็ตถูกตัดการเชื่อมต่อ/ปิดใช้งานในตั้งค่า → การเชื่อมต่อ หรือกำลังดูคนละบริษัท
`INVALID_IDENTITY_HASH`	คำนวณ hash จากค่าผิด (ต้องเซ็นเฉพาะ `userId`), ใช้รหัสลับผิด, หรือรหัสลับถูกหมุนเวียนหลังจากเรนเดอร์หน้าเว็บไปแล้ว
เปิดโหมดระบุตัวตนแล้วไม่มีอะไรเกิดขึ้น	`identify` ไม่ครบ — ต้องมีทั้ง `userId` และ `userHash`
ฟอร์มก่อนแช็ตขึ้นซ้ำ ๆ	ปกติสำหรับเบราว์เซอร์ใหม่ ถ้าเกิดกับผู้เยี่ยมชมที่กลับมา แสดงว่า `localStorage` ถูกบล็อก (โหมดส่วนตัว, แถบยินยอมคุกกี้)
ประวัติหายเมื่อเปลี่ยนเบราว์เซอร์	ปกติสำหรับผู้เยี่ยมชมไม่ระบุตัวตน เพราะประวัติผูกกับเบราว์เซอร์ — ถ้าต้องการประวัติข้ามอุปกรณ์ให้ใช้โหมดระบุตัวตน
แนบไฟล์ไม่ได้	ไฟล์เกิน 25 MB หรือนามสกุลไม่อยู่ในรายการที่อนุญาต (หัวข้อ 4)
แท็บบทความ/ค้นหาว่างเปล่า	ยังไม่มีบทความ Help Center ที่เผยแพร่สำหรับบริษัทนี้
AI ไม่ตอบเลย	สวิตช์หลักของ AI ปิด หรือช่องทางวิดเจ็ตถูกปิดที่ตั้งค่า → AI → ช่องทาง (หัวข้อ 9)
ปุ่มลอยทับปุ่มลอยเดิมของเว็บ	ตั้ง `position: 'left'` หรือใช้ `hideLauncher: true` แล้วสั่งเปิดจาก UI ของคุณเอง (หัวข้อ 7)

13. คำถามที่พบบ่อย

ใช้กับ single-page app ได้ไหม
ได้ loader ทำงานครั้งเดียวและอยู่รอดข้ามการเปลี่ยนหน้าแบบ client-side อย่าแทรกโค้ดใหม่ทุกครั้งที่เปลี่ยน route ให้ใส่ครั้งเดียวใน root layout

สร้างได้มากกว่าหนึ่งวิดเจ็ตไหม
ได้ สร้างหนึ่งตัวต่อหนึ่งเว็บหรือหนึ่งแบรนด์ แต่ละตัวมี publicKey, ธีม และรายการโดเมนของตัวเอง และแสดงเป็นช่องทางแยกกันในคอนโซล วิดเจ็ตนับรวมในจำนวนช่องทางตามแพ็กเกจ

ปรับหน้าตาแผงแช็ตเองได้ไหม
ตั้งสีธีมได้ แต่เลย์เอาต์ปรับไม่ได้ และ CSS บนหน้าเว็บคุณเข้าไปในเนื้อ iframe ไม่ได้ตามการออกแบบ

ใส่ผ่าน Google Tag Manager ได้ไหม
ได้ ใช้ Custom HTML tag วางโค้ดตามปกติ แต่ถ้าใช้โหมดระบุตัวตน ต้องมี hash ให้ GTM เข้าถึงได้ ซึ่งมักหมายถึงตัวแปร data layer ที่เรนเดอร์มาจากเซิร์ฟเวอร์

ต้องขอความยินยอมคุกกี้ไหม
วิดเจ็ตเก็บ visitor token ใน localStorage เพื่อให้สนทนาต่อเนื่องได้ ส่วนจะเข้าข่ายต้องขอความยินยอมตามนโยบายของคุณหรือไม่ เป็นดุลพินิจของคุณ — วิดเจ็ตทำงานได้แม้ไม่มี token เพียงแต่จะเริ่มบทสนทนาใหม่ทุกครั้งที่เข้าเว็บ

นอกเวลาทำการเป็นอย่างไร
เหมือนช่องทางอื่น ข้อความต้อนรับ/ตอบกลับอัตโนมัติ และการตั้งค่าเวลาทำการของ AI มีผลตามที่ตั้งไว้ ผู้เยี่ยมชมยังส่งข้อความได้ และเจ้าหน้าที่มารับภายหลัง

เปิดแผงแช็ตจากลิงก์ในอีเมลได้ไหม
ใช้ autoOpen: true บนหน้า landing เฉพาะ (หัวข้อ 7) เช่นแสดงเมื่อมี query param ?support=1

ระบบของเราดึงบทสนทนาไปใช้ได้ไหม
ไม่ได้ผ่านตัววิดเจ็ตเอง บทสนทนาของวิดเจ็ตอยู่ในคอนโซลเหมือนห้องแช็ตทั่วไป ถ้าต้องการดึงด้วยโปรแกรม ใช้ One Bear Public API (ตั้งค่า → นักพัฒนา → API key) เพื่ออ่านห้องและข้อความ หรือสมัคร Webhook (message.received, room.created, …) เพื่อรับเหตุการณ์ทันทีที่เกิด — ทั้งสองอย่างมีเอกสารในส่วน One Bear Public API ของไซต์นี้

14. แอปมือถือ (Android · iOS · Flutter)

ฝังบทสนทนาเดียวกันลงในแอปของคุณเองได้ SDK จะห่อแผงแช็ตของวิดเจ็ตไว้ใน WebView แบบ native หลัง API เล็ก ๆ ชุดหนึ่ง แอปของคุณจึงไม่ต้องคุยกับแผงแช็ตเอง และใช้ วิดเจ็ตตัวเดียวกัน (publicKey, ธีม, โดเมนที่อนุญาต, รหัสลับตัวตน) กับโค้ดฝังบนเว็บ ไม่ต้องสร้างอะไรเพิ่มในคอนโซล

แพลตฟอร์ม	แพ็กเกจ	เวอร์ชันต่ำสุด
Flutter (Android + iOS)	`onebear_chat` บน pub.dev — `flutter pub add onebear_chat`	Flutter 3.24 · Dart 3.5 · Android minSdk 24 · iOS 14
iOS (native)	`OneBearChat` ผ่าน Swift Package Manager หรือ CocoaPods จาก `github.com/GofiveCorp/onebear-ios`	iOS 14 · Swift 5.9
Android (native)	`co.gofive.onebear:onebear-chat` — ปัจจุบันมาพร้อมในปลั๊กอิน Flutter ถ้าต้องการ artifact แยกให้ติดต่อเรา	minSdk 24 · compileSdk 35

API เหมือนกันทุกแพลตฟอร์ม:

เหตุการณ์ (ChatOpened, ChatClosed, NewMessageReceived, LinkTapped, ErrorOccurred) มีให้เป็น stream บน Flutter และ delegate บน iOS/Android

สิ่งที่ต่างจากโค้ดฝังบนเว็บ:

ไม่มีปุ่มลอย คุณเป็นคนวางจุดเข้า (เมนู, แท็บ, ปุ่ม) แล้วเรียก present() ใช้ unreadCount ทำ badge เอง

เต็มจอเท่านั้น ออกจากแช็ตด้วยท่าย้อนกลับ / ปัดจากขอบของแพลตฟอร์ม

แนบไฟล์ ใช้ได้บน Android และเว็บ ส่วน iOS ยังไม่รองรับใน SDK

ไม่มี push notification จาก SDK — คำตอบที่มาระหว่างแอปปิดจะเห็นเมื่อเปิดแช็ตครั้งถัดไป

ลิงก์ที่เจ้าหน้าที่ส่งเปิดใน Custom Tabs (Android) / SFSafariViewController (iOS) ส่วนบทความ Help Center และวิดีโอที่ฝังไว้แสดงในแช็ตได้เลย

อัปเดต SDK ให้ทันเสมอ — แผงแช็ตของมือถือถูกรวมอยู่ในแพ็กเกจ การแก้ไข (คีย์บอร์ด, การซูม, embed ในบทความ) จึงมาพร้อมเวอร์ชันใหม่ของแพ็กเกจ ไม่ได้อัปเดตเองเหมือนวิดเจ็ตบนเว็บ

OneBear Live Chat Widget — คู่มือตั้งค่าและการผสานระบบ

1. หลักการทำงาน#

2. สร้างวิดเจ็ตในคอนโซล#

3. วางโค้ดฝัง#

4. สิ่งที่ผู้เยี่ยมชมเห็น#

5. โดเมนเว็บไซต์ที่อนุญาต (ต้องอ่าน)#

6. โหมดระบุตัวตน (ผู้เยี่ยมชมที่ยืนยันตัวตนแล้ว)#

6.1 ดูรหัสลับตัวตน#

6.2 คำนวณ userHash บนเซิร์ฟเวอร์ของคุณ#

6.3 ส่งค่าให้วิดเจ็ต#

7. การควบคุมด้วยโค้ด#

8. ความต่อเนื่องของบทสนทนา#

9. AI agent และการส่งต่อให้มนุษย์ (handoff)#

10. ข้อจำกัด และสิ่งที่วิดเจ็ตยังทำไม่ได้#

11. ความปลอดภัย#

12. แก้ปัญหาเบื้องต้น#

13. คำถามที่พบบ่อย#

14. แอปมือถือ (Android · iOS · Flutter)#