Trước khi bắt đầu

Sau khi đăng ký kênh, vào «Cài đặt kênh → Cách tích hợp» trong bảng điều khiển sẽ lấy được hai thứ: mã kênh và khóa API. Mã kênh xuất hiện trong mã nguồn trang nên là công khai; khóa API chỉ được để ở phía máy chủ của bạn.

Trang đó còn có một liên kết kiểm tra không kèm tham số nào, chép vào trình duyệt mở lên là biết kênh đã thông hay chưa, nên làm bước này trước.

Nhúng script

Góc dưới bên phải website sẽ xuất hiện bong bóng, bấm vào là khung chat. Đặt trước </body>:

<script src="https://chat.jstosecret.com/embed.js"
        data-channel="MÃ_KÊNH_CỦA_BẠN"
        defer></script>

Khung chat chạy trong iframe nên CSS trang của bạn và của chúng tôi không đụng nhau. Script chỉ lo chèn bong bóng và tạo iframe, không động tới bất kỳ phần tử nào khác trên trang.

Dùng liên kết

Mở ra là trang chat luôn, hợp với trình duyệt trong ứng dụng, email, biên nhận phiếu hỗ trợ — những chỗ không chèn script được.

https://chat.jstosecret.com/?c=MÃ_KÊNH_CỦA_BẠN

Truyền danh tính người dùng

Gửi kèm thông tin người dùng trong hệ thống của bạn thì vừa vào chat nhân viên đã biết ai đang hỏi, khách quay lại cũng được ưu tiên nối về đúng nhân viên đã tiếp lần trước. Cả ba trường đều không bắt buộc, có gì gửi nấy.

Quá dài sẽ bị cắt bớt khi lưu, không báo lỗi và cũng không làm hỏng cả lần tích hợp. Độ dài tính theo ký tự chứ không phải byte — một chữ Hán hay một emoji đều có thể chiếm nhiều vị trí ký tự.

<!-- Cách nhúng script: thay placeholder bằng giá trị thật ở phía máy chủ -->
<script src="https://chat.jstosecret.com/embed.js"
        data-channel="MÃ_KÊNH_CỦA_BẠN"
        data-uid="10001"
        data-email="[email protected]"
        data-extra="Khách VIP đơn#8823"
        defer></script>

Khách được khớp như thế nào

Ba trường danh tính là thứ tự ưu tiên loại trừ nhau, không phải lùi dần từng cái:

Đã gửi uid thì chỉ dùng uid — đây là điều quan trọng nhất. Quay về trường khác sẽ lẫn danh tính: bạn đổi hệ thống người dùng khiến uid thay đổi, hoặc hai nhân viên dùng chung một [email protected], thì người đến sau sẽ tiếp quản hồ sơ của người trước và đọc được toàn bộ lịch sử trò chuyện. uid là khẳng định danh tính do chính bạn đưa ra; khi nó nói "đây là người dùng mới", chúng tôi không nên lấy một trường yếu hơn để phủ quyết.

Khi tích hợp cần lưu ý hai điểm:

• Đã có uid thì luôn gửi kèm. Lần này gửi uid, lần sau chỉ gửi email thì cùng một người sẽ bị tính thành hai khách, lịch sử trò chuyện không khớp được.
• uid phải ổn định. Hãy dùng giá trị không đổi như khóa chính trong cơ sở dữ liệu — đừng dùng số điện thoại hay email vì người dùng tự sửa được, sửa một lần là thành người khác.

Phạm vi nhận diện là trong phạm vi một kênh. Cùng một người ở hai kênh của bạn là hai bản ghi độc lập, phiên trò chuyện và lịch sử không thấy được của nhau; đó là một phần của cơ chế cô lập kênh.

Ký tự đặc biệt trong thông tin bổ sung

Thông tin bổ sung là tham số dễ sinh chuyện nhất, vì nội dung của nó hoàn toàn do nghiệp vụ quyết định — mã đơn, địa chỉ, yêu cầu của khách, cái gì cũng có thể nhét vào. Ba quy tắc:

• Ghép liên kết thì nhất định phải dùng encodeURIComponent(), đừng tự nối chuỗi. &, #, ?, + hay dấu cách không mã hóa sẽ cắt cụt liên kết hoặc lọt sang tham số khác — B trong extra=A&B sẽ bị hiểu thành một tham số riêng.
• Ghi vào thuộc tính data-extra thì phải escape HTML: " thành ", < thành <. Nếu không, chỉ một dấu nháy là thuộc tính đóng sớm và cả thẻ script hỏng theo. Ở phía máy chủ, dùng sẵn cơ chế escape của template engine là đủ.
• Ký tự xuống dòng và tab sẽ bị thay bằng dấu cách, để nguyên chỉ làm vỡ bố cục ở phía tiếp nhận.

Emoji và chữ viết các nước dùng trực tiếp được, lưu trữ theo utf8mb4.

// Cách ghép đúng
const url = 'https://chat.jstosecret.com/?c=MÃ_KÊNH_CỦA_BẠN'
  + '&uid=' + encodeURIComponent(user.id)
  + '&extra=' + encodeURIComponent('Khách VIP đơn#8823 yêu cầu:gấp&ưu tiên')

// Sai: & và # chưa mã hóa, extra chỉ nhận được "Khách VIP đơn"
// còn "ưu tiên" ở phía sau biến thành một tham số lạ tên "ưu tiên"
const bad = base + '&extra=Khách VIP đơn#8823 yêu cầu:gấp&ưu tiên'

Các tham số này đều ở dạng công khai

Chúng nằm ngay trong mã nguồn trang và trên thanh địa chỉ, ai cũng sửa được. Nghĩa là chỉ dựa vào cách này để truyền danh tính thì người khác đổi uid một cái là mạo danh được người dùng khác và xem được lịch sử trò chuyện của người đó. Nếu cuộc trò chuyện có đụng tới đơn hàng, tài khoản, hãy dùng cách vé ở bên dưới.

Vé dùng một lần

Máy chủ của bạn dùng khóa API đổi lấy một chiếc vé, rồi ghép vé đó vào liên kết đưa cho khách. URL không lộ thông tin người dùng, vé dùng một lần là hết hiệu lực, liên kết chuyển tiếp cho người khác sẽ không mở được lần thứ hai.

Bước 1: máy chủ đổi lấy vé

curl -X POST https://chat.jstosecret.com/api/open/ticket \
  -H 'Content-Type: application/json' \
  -H 'X-Channel-Secret: KHÓA_API_CỦA_BẠN' \
  -d '{"channelCode":"MÃ_KÊNH_CỦA_BẠN","uid":"10001","extra":"Khách VIP đơn#8823"}'

# Kết quả trả về
{ "ticket": "a1b2c3...", "expiresIn": 300 }

Bước 2: đưa vé cho khách

# Cách dùng liên kết
https://chat.jstosecret.com/?c=MÃ_KÊNH_CỦA_BẠN&ticket=a1b2c3...

# Hoặc cách nhúng script
<script src="https://chat.jstosecret.com/embed.js"
        data-channel="MÃ_KÊNH_CỦA_BẠN"
        data-ticket="a1b2c3..."
        defer></script>

• Khóa API chỉ được để ở phía máy chủ của bạn. Đưa ra giao diện là coi như công khai, ai cũng ký được danh tính của người khác.
• Vé mặc định có hiệu lực 5 phút, dùng expiresIn để đặt từ 30 đến 1800 giây.
• Khách tải lại trang không bị ảnh hưởng: lần đầu vào xong sẽ đổi sang token cục bộ dài hạn, không dùng vé nữa.
• Vé chỉ truyền danh tính chứ không lưu danh tính. Ba tháng sau khách quay lại, đổi một chiếc vé mới là xong, lịch sử vẫn còn nguyên.

Giao diện & vị trí

Biểu tượng, vị trí, khoảng cách lề, màu chủ đạo của bong bóng chat, cùng tên và biểu tượng dự án ở đầu khung chat, đều chỉnh trong «Cài đặt kênh» của bảng điều khiển. Chỉnh xong khách chỉ cần tải lại trang là có hiệu lực, không phải dán lại mã.

Khi có website cần chỉnh riêng vị trí (chẳng hạn góc dưới bên phải đã bị nút khác chiếm), có thể thêm thuộc tính để ghi đè:

<script src="https://chat.jstosecret.com/embed.js"
        data-channel="MÃ_KÊNH_CỦA_BẠN"
        data-position="left-bottom"
        data-offset-x="24"
        data-offset-y="90"
        defer></script>

Lưu ý mấy thuộc tính này có độ ưu tiên cao hơn, thêm vào rồi thì vị trí của website này bị cố định, sau đó chỉnh trong bảng điều khiển sẽ không có tác dụng. Chỉ dùng khi thật sự cần.

Tên miền riêng

Từ gói Chuyên nghiệp trở lên được tặng tên miền riêng. Khung chat và bong bóng chạy trên tên miền của chính bạn, ví dụ chat.yourdomain.com, địa chỉ khách nhìn thấy là thương hiệu của bạn.

Vì sao đáng cấu hình

Ngoài thương hiệu, lợi ích thực tế hơn là cô lập rủi ro sự cố. Mặc định mọi khách hàng dùng chung tên miền chat của chúng tôi — chỉ cần một bên bị một mạng nào đó, một nhà mạng nào đó hay một tường lửa doanh nghiệp nào đó chặn lại, là tất cả cùng không mở được. Còn bạn chỉ thấy "khách truy cập đột nhiên không kết nối được", và sẽ đi tìm nguyên nhân sai hoàn toàn.

Dùng tên miền của chính mình thì sự cố của người khác không ảnh hưởng tới bạn; đến lượt bạn gặp trục trặc, đổi một bản ghi phân giải là khôi phục được, không phải xếp hàng chờ chúng tôi. Gói Cao cấp cho 5 tên miền, nhiều thương hiệu hay nhiều website dùng riêng từng cái, không kéo nhau xuống.

Cấu hình thế nào

• Bạn thêm một bản ghi CNAME trong DNS, trỏ về địa chỉ chúng tôi cung cấp
• Chứng chỉ do chúng tôi đăng ký và gia hạn, bạn không phải bận tâm
• Có hiệu lực rồi thì đổi địa chỉ trong mã tích hợp sang tên miền mới, còn lại không phải sửa gì

Cần kích hoạt thì liên hệ [email protected], cho chúng tôi biết tên miền bạn muốn dùng.

Điều khiển thủ công

Muốn dùng nút trên trang của mình để mở khung chat thay cho bong bóng mặc định:

// Dùng được sau khi script đã tải
window.KefuWidget.open()
window.KefuWidget.close()
window.KefuWidget.toggle()

Bản thân bong bóng không ẩn được — nếu bạn chỉ muốn dùng nút của mình, hãy đẩy lề của nó ra ngoài màn hình, ví dụ data-offset-x="-100".

Tích hợp gặp vấn đề

Trước hết xem thông báo lỗi mà máy chủ trả về. Phần lớn sự cố tích hợp (ghi sai mã kênh, vé hết hạn, để khóa API ở phía giao diện) đều nêu thẳng nguyên nhân trong phản hồi.

• Hỗ trợ kỹ thuật: Telegram @chatcocoaofficial, trực 24/7
• Kinh doanh & tùy chỉnh: [email protected]