Chatwoot

Chatwoot là nền tảng chăm sóc khách hàng mã nguồn mở, gom tin nhắn từ live chat trên website, email, Facebook, WhatsApp, Telegram... về một giao diện chung. FlashPanel cài Chatwoot thành một website độc lập trên máy chủ của bạn.

Yêu cầu

Máy chủ thuộc gói trả phí. Mục Chatwoot hiển thị biểu tượng khóa nếu máy chủ chưa nâng cấp.
Máy chủ đã cài web server (Nginx hoặc Apache). FlashPanel tự cài thêm PostgreSQL 16 nếu máy chủ chưa có. Mỗi website Chatwoot có Redis riêng, không dùng chung Redis của máy chủ.
Cấu hình tối thiểu: CPU 4 nhân và RAM 4 GB (nên dùng 8 nhân, 8 GB nếu lượng hội thoại lớn).
Một website mới dành riêng cho Chatwoot (ví dụ chat.domain.com). Mã nguồn hiện có của website sẽ bị ghi đè.
Một cổng còn trống để chạy Chatwoot. Cổng không được trùng với Proxy Port của website khác trên máy chủ và không được là 80, 443, 2022.

Cài đặt

Tạo website mới rồi bấm vào tên website trong danh sách để mở trang quản lý.
Bấm menu Cài đặt Mã nguồn, rồi bấm vào biểu tượng Chatwoot.
Nhập Cổng mà Chatwoot sẽ chạy (mặc định là Proxy Port của website hoặc 3000).
Đọc cảnh báo, đánh dấu ô Đúng, làm đi! rồi bấm Cài đặt Chatwoot.

Quá trình cài đặt mất khoảng 20–40 phút (lần cài Chatwoot đầu tiên trên máy chủ lâu hơn vì phải build Ruby). Theo dõi tiến trình ở menu Sự kiện của website. Khi cài xong, truy cập website và điền thông tin để tạo tài khoản quản trị viên.

TIP

Cài SSL cho website trước khi nhúng Chatwoot vào website khác, vì đoạn mã nhúng nên dùng địa chỉ https://.

Sử dụng

Thêm live chat vào website

Trong Chatwoot, mở Settings > Inboxes rồi bấm nút thêm inbox mới.
Chọn kênh Website, nhập thông tin rồi bấm Create Inbox.
Chọn những người được phép trả lời trong inbox rồi bấm Add Agents.
Chatwoot hiển thị đoạn mã nhúng (cũng xem được ở tab Configuration của inbox), có dạng:

html

<script>
  (function(d,t) {
    var BASE_URL="https://chat.domain.com";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.chatwootSDK.run({
        websiteToken: '*****',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>

Chèn đoạn mã vào website cần dùng live chat, thường đặt trước thẻ </body>.

Gửi thông tin người dùng đã đăng nhập

Mặc định, khách gửi tin nhắn hiển thị với tên ngẫu nhiên. Với website có người dùng đăng nhập, thêm đoạn sau (sau đoạn mã nhúng) để Chatwoot hiển thị tên, email... của người gửi:

html

<script>
window.addEventListener("chatwoot:ready", function () {
    window.$chatwoot.setUser("user-id", {
        name: "John Doe", // Tên người dùng
        email: "[email protected]", // Email người dùng
        avatar_url: "", // Ảnh đại diện
        phone_number: "", // Số điện thoại
        identifier_hash: "", // Mã xác thực, xem bên dưới
    });
});
</script>

Trường identifier_hash xác nhận user-id do máy chủ của bạn tạo ra, tránh bị giả mạo. Lấy HMAC token ở mục User Identity Validation trong tab Configuration của inbox, rồi tạo mã ở phía máy chủ, ví dụ với PHP:

php

hash_hmac('sha256', 'user-id', 'chatwoot-inbox-hmac-token');

Bật Enforce User Identity Validation trong cùng tab để Chatwoot từ chối các yêu cầu không xác thực được.

Nâng cấp Chatwoot

Khi có phiên bản mới, bảng Hành động ở đầu trang Trang chủ của website hiển thị nút upgrade (ghi chú Nâng cấp chatwoot lên phiên bản ổn định mới nhất kèm số phiên bản). Bấm nút này để nâng cấp. Quá trình nâng cấp mất khoảng 10–30 phút, Chatwoot vẫn chạy bản cũ cho tới bước cuối.

Nếu bạn đã sửa mã nguồn Chatwoot trên máy chủ, việc nâng cấp sẽ dừng lại và liệt kê các file đã sửa thay vì ghi đè. Commit hoặc hoàn tác các thay đổi đó rồi nâng cấp lại.

Khởi động lại và xem log

Bấm nút restart trong bảng Hành động để khởi động lại Chatwoot. Để xem log, kết nối SSH vào máy chủ với user root rồi chạy lệnh dưới đây, thay 123456 bằng ID hiển thị trong thẻ thông tin ở trang Trang chủ của website:

Lệnh	Chức năng
`journalctl -u chatwoot-web-123456 -f`	Xem log của web server Chatwoot
`journalctl -u chatwoot-worker-123456 -f`	Xem log của worker xử lý tác vụ nền
`systemctl status chatwoot123456.target`	Xem trạng thái các dịch vụ của Chatwoot

Bấm Ctrl + C để thoát khi đang xem log.

Gỡ cài đặt

Bấm menu Trang chủ của website.
Trong nhóm Khu vực nguy hiểm, bấm Xóa code.
Đánh dấu Xóa cơ sở dữ liệu và Xóa người dùng cơ sở dữ liệu nếu muốn xóa luôn toàn bộ dữ liệu Chatwoot (hội thoại, liên hệ, tài khoản).
Đánh dấu Khôi phục về trang mặc định? để xóa tệp Chatwoot và đưa website về trang mặc định.
Đánh dấu Đúng, làm đi! rồi bấm Xóa code.

Chatwoot và Redis riêng của website sẽ được dừng và gỡ khỏi danh sách dịch vụ chạy nền của máy chủ. PostgreSQL vẫn được giữ lại trên máy chủ.

Khắc phục sự cố

Không đủ bộ nhớ khi cài hoặc nâng cấp

Cài đặt hoặc nâng cấp Chatwoot thất bại với một trong các lỗi:

text

❌ Chatwoot needs a server with at least 4 GB of RAM, this server has 1910 MB
❌ Not enough memory (RAM and swap) to build Chatwoot: 3810 MB RAM + 1023 MB swap, at least 6000 MB in total is needed
❌ Not enough memory (RAM and swap) to build Chatwoot

Khi cài và nâng cấp, Chatwoot phải build lại giao diện, bước này cần khoảng 6 GB RAM và swap cộng lại. Hai lỗi đầu báo ngay từ đầu, website chưa bị thay đổi: máy chủ có dưới 4 GB RAM, hoặc RAM cộng swap dưới 6 GB (ví dụ máy 4 GB với swap mặc định 1 GB). Lỗi cuối xảy ra giữa lúc build khi RAM còn trống cộng swap không đủ, thường gặp khi máy chủ đang chạy nhiều website hoặc nhiều ứng dụng khác.

Chọn một trong các cách sau rồi cài lại, hoặc bấm lại nút upgrade nếu lỗi xảy ra khi nâng cấp:

Tăng swap tạm thời: mở cài đặt Swap của máy chủ và chọn 4 GB. Bước build sẽ chậm hơn vì swap chậm hơn RAM. Sau khi xong, bạn có thể giảm swap về mức cũ.
Nâng cấp máy chủ lên RAM 4 GB trở lên (cách duy nhất khi máy chủ có dưới 4 GB RAM). Nên dùng 8 GB nếu chạy nhiều website Chatwoot trên cùng máy chủ.
Dừng bớt ứng dụng tốn RAM trên máy chủ trong lúc cài hoặc nâng cấp.

Lưu ý

Khi cài Chatwoot, thư mục web của website được đặt thành /public và cấu hình Nginx của website được điều chỉnh tự động cho Chatwoot. Cấu hình này được hoàn tác khi gỡ cài đặt.
Chatwoot chạy bằng người dùng hệ thống của website và chỉ thấy thư mục home của người dùng đó, không đọc được dữ liệu của website khác trên máy chủ.

Chatwoot ​

Yêu cầu ​

Cài đặt ​

Sử dụng ​

Thêm live chat vào website ​

Gửi thông tin người dùng đã đăng nhập ​

Nâng cấp Chatwoot ​

Khởi động lại và xem log ​

Gỡ cài đặt ​

Khắc phục sự cố ​

Không đủ bộ nhớ khi cài hoặc nâng cấp ​

Lưu ý ​