# Cấu hình widget

Phần lớn cài đặt của widget nằm trong dashboard và áp dụng cho mọi trang có đoạn mã. Một vài cài đặt có thể ghi đè theo từng trang bằng `window.HATANG_CONFIG`. Trang này liệt kê mọi cài đặt, giới hạn của chúng và cách widget dùng chúng.

## Trước khi bắt đầu

- Bạn đã [cài widget](https://hatang.dev/vi/docs/guides/support/web-widget/install.md) và tạo kênh website.
- Vai trò của bạn có quyền `chat:manage`.

## Cài đặt nằm ở đâu

Vào **Hỗ trợ → Kênh** rồi chọn website. Trang site có ba tab:

| Tab | Nội dung |
|---|---|
| **Cài đặt** | Đoạn mã, mọi mục trên trang này, mã bí mật định danh và xoá site. |
| **Tự động hoá** | Nhắc lại, thông báo social proof, đánh giá hài lòng (CSAT) và theo dõi chuyển đổi, cùng các luồng và chiến dịch đang chạy trên site. |
| **Ứng dụng** | Các ứng dụng di động dùng cài đặt widget của site này. Xem [Ứng dụng di động](https://hatang.dev/vi/docs/guides/support/mobile-apps.md). |

Khung **Xem trước** bên cạnh form chạy đúng widget thật và cập nhật theo các thay đổi chưa lưu. Chuyển giữa **Đang mở**, **Nút chat**, **Ngoại tuyến**, **Form trước chat**, và giữa **Máy tính**, **Điện thoại**.

Bấm **Lưu cài đặt** khi xong. Widget cập nhật trong vòng một phút.

## Chung

| Cài đặt | Giá trị | Ghi chú |
|---|---|---|
| **Tên miền** | Một host, ví dụ `shop.vn` | Widget tải trên host này và các tên miền phụ. |
| **Tiêu đề widget** | Văn bản | Hiện trên đầu widget. Đây cũng là tên site trong dashboard. |
| **Origin được phép thêm** | Mỗi dòng một origin | Cho môi trường phát triển và bản preview, ví dụ `http://localhost:3000`. Phải khớp chính xác, kể cả scheme và cổng. |
| **Trạng thái** | **Đang hoạt động**, **Đã tắt (ẩn widget)** | Tắt thì widget ẩn ở mọi nơi, lịch sử vẫn giữ. |
| **Màu** | Mã màu hex, mặc định `#111111` | Màu nút chat, đầu khung và bong bóng tin của khách. |
| **Vị trí** | **Góc dưới phải** (mặc định), **Góc dưới trái** | Ghi đè được theo trang bằng `position`. |
| **Giao diện** | **Sáng** (mặc định), **Tối**, **Theo hệ thống của khách** | "Theo hệ thống của khách" đi theo chế độ sáng/tối của máy khách và đổi ngay khi máy đổi. |

## Nút mở chat

Nút tròn ở góc màn hình.

| Cài đặt | Giá trị | Ghi chú |
|---|---|---|
| **Biểu tượng** | **Bong bóng chat** (mặc định), **Tai nghe hỗ trợ**, **Dấu hỏi**, **Tin nhắn tròn** | Biểu tượng có sẵn, theo màu của widget. |
| **Chữ trên nút (tiếng Việt)** / **Chữ trên nút (tiếng Anh)** | Tối đa 24 ký tự mỗi ô; để trống là chỉ có biểu tượng | Biến nút tròn thành nút dài như "Hỗ trợ". Thêm chữ nếu website có tính năng chat riêng, để khách không nhầm hai thứ. |
| **Ảnh riêng (tuỳ chọn)** | URL `https://` của ảnh vuông, tối đa 500 ký tự | Thay cho biểu tượng, ví dụ logo của bạn. |

Khi khung chat đang đóng, nút chat có huy hiệu đỏ ghi số tin trả lời chưa đọc.

## Kích thước khung và vị trí nút

| Cài đặt | Giá trị | Ghi chú |
|---|---|---|
| **Độ rộng khung chat** | **Hẹp (340px)**, **Vừa (380px)** (mặc định), **Rộng (440px)** | Trên màn hình rộng từ 640px trở xuống, khung chat mở toàn màn hình. |
| **Desktop: dưới** / **Desktop: cạnh** | 0–400 px; trống là 20px | Khoảng cách từ nút chat tới góc. |
| **Điện thoại: dưới** / **Điện thoại: cạnh** | 0–400 px; trống là 16px | Dùng cho màn hình rộng từ 640px trở xuống. Nếu để trống cả hai ô điện thoại nhưng có đặt giá trị desktop, điện thoại dùng giá trị desktop. |

Widget tự cộng thêm vùng an toàn (safe area) của máy, ví dụ thanh home của iPhone, vào khoảng cách dưới. Nếu website có thanh điều hướng dưới cùng trên điện thoại, tăng **Điện thoại: dưới** để nút nằm trên thanh đó. `offset` và `mobileOffset` trong `window.HATANG_CONFIG` ghi đè từng giá trị này.

## Đầu khung chat

| Cài đặt | Giá trị | Ghi chú |
|---|---|---|
| **Hiển thị** | **Ảnh nhân viên đang trực** (mặc định), **Ảnh nhân viên đang trực, không ai trực thì logo**, **Ảnh một nhân viên được chọn**, **Logo doanh nghiệp** | Chế độ nhân viên hiện tối đa ba người đang trực. Lựa chọn thứ hai chuyển sang logo khi không ai trực. **Ảnh một nhân viên được chọn** luôn hiện người được chọn ở ô **Nhân viên hiển thị**, dù họ có trực hay không, và hiện logo nếu người đó rời doanh nghiệp. Chế độ logo hiện logo bên dưới, hoặc chữ cái đầu của tiêu đề widget. Mọi SDK đều hiển thị được: server tự quy về ảnh nhân viên hoặc logo. |
| **Logo (URL https, ảnh vuông)** | URL `https://`, tối đa 500 ký tự | Dùng cho **Logo doanh nghiệp**, và làm ảnh dự phòng cho hai lựa chọn ở trên. |
| **Dòng giới thiệu (Tiếng Việt)** / **Dòng giới thiệu (English)** | Tối đa 120 ký tự mỗi ô | Dòng dưới tiêu đề, ví dụ "Thường trả lời trong vài phút". |

Dưới dòng giới thiệu, đầu khung hiện "Chúng tôi đang trực tuyến", hoặc "Hiện chúng tôi vắng mặt" kèm giờ quay lại khi có đặt giờ làm việc.

## Tin nhắn

| Cài đặt | Giá trị | Ghi chú |
|---|---|---|
| **Ngôn ngữ mặc định** | **Tự động (theo trình duyệt)** (mặc định), Tiếng Việt, English | Xem [Ngôn ngữ](#language) bên dưới. |
| **Lời chào (vi)** / **Lời chào (en)** | Tối đa 300 ký tự | Bong bóng đầu tiên khách thấy trong khung chat trống. |
| **Tin nhắn vắng mặt (vi)** / **Tin nhắn vắng mặt (en)** | Tối đa 300 ký tự | Thông báo trên đầu khung chat khi không ai trực. |
| **Hiện lời chào** | Bật mặc định | Tắt để khung chat bắt đầu trống. |
| **Hiện lời chào trên điện thoại** | Bật mặc định | Tắt để chỉ hiện lời chào trên máy tính. |
| **Ký tên lời chào** | **Không ký tên** (mặc định), **Nhân viên đang trực** | Khi chọn nhân viên đang trực, tên người trực đầu tiên hiện dưới lời chào. |
| **Bật lời chào lên trên nút chat sau** | 0–120 giây; 0 = không | Hiện lời chào thành bong bóng phía trên nút chat đang đóng, một lần mỗi phiên trình duyệt, nếu khách chưa có hội thoại. |

### Ngôn ngữ {#language}

Widget dùng tiếng Việt hoặc tiếng Anh, chọn theo thứ tự:

1. Ngôn ngữ trang đã đặt trước đó bằng lệnh `setLocale` (trình duyệt ghi nhớ).
2. `locale` trong `window.HATANG_CONFIG`.
3. **Ngôn ngữ mặc định** trong dashboard, trừ khi là **Tự động (theo trình duyệt)**.
4. Ngôn ngữ trình duyệt: tiếng Việt nếu bắt đầu bằng `vi`, ngược lại là tiếng Anh.

## Kênh liên hệ khác

Các nút dưới đầu khung để khách liên hệ qua kênh khác.

| Cài đặt | Ghi chú |
|---|---|
| **Nút Zalo** | Mở Zalo Official Account của bạn. Chỉ dùng được khi website đã kết nối Zalo OA; nếu chưa, mục này hiện **chưa kết nối**. Xem [Zalo OA](https://hatang.dev/vi/help/channels/zalo-oa). |
| **Nút Messenger** | Mở Trang Facebook của bạn trong Messenger. Chỉ dùng được khi website đã kết nối Trang. Xem [Messenger và Instagram](https://hatang.dev/vi/help/channels/messenger-instagram). |
| **Số điện thoại (nút gọi)** | Số điện thoại, ví dụ `0901 234 567` hoặc `+84 901 234 567`. Mở trình quay số. |
| **Email (nút gửi email)** | Địa chỉ email. Mở ứng dụng thư của khách. |

## Form trước khi chat

Hỏi thông tin trước tin nhắn đầu tiên của khách.

| Cài đặt | Giá trị | Ghi chú |
|---|---|---|
| **Hỏi thông tin trước tin nhắn đầu tiên** | Tắt mặc định | Bật form. |
| **Tên** | **Không hỏi**, **Không bắt buộc** (mặc định), **Bắt buộc** | |
| **Số điện thoại** | **Không hỏi**, **Không bắt buộc**, **Bắt buộc** (mặc định) | Số Việt Nam (bắt đầu bằng `0`, `84` hoặc `+84`) phải là số di động 10 chữ số hợp lệ; số nước khác cần 8–15 chữ số. |
| **Email** | **Không hỏi** (mặc định), **Không bắt buộc**, **Bắt buộc** | |

Form được bỏ qua với khách đã được [nhận diện có chữ ký](https://hatang.dev/vi/docs/guides/support/web-widget/identity-verification.md) và khách đã điền trước đó trên trình duyệt này. Widget chỉ hỏi những trường chưa biết. Nếu không còn trường bắt buộc nào cần hỏi, form được bỏ qua. Thông tin khách điền được lưu vào khách truy cập và hồ sơ khách hàng.

## Nơi hiện widget

| Cài đặt | Giá trị | Ghi chú |
|---|---|---|
| **Thiết bị** | **Mọi thiết bị** (mặc định), **Chỉ máy tính**, **Chỉ điện thoại** | "Điện thoại" là màn hình rộng từ 640px trở xuống. |
| **Chỉ hiện trên URL chứa** | Tối đa 20 dòng, mỗi dòng 200 ký tự; trống = mọi trang | Widget hiện khi URL của trang chứa một trong các dòng. |
| **Ẩn trên URL chứa** | Tối đa 20 dòng, mỗi dòng 200 ký tự | Widget ẩn khi URL của trang chứa một trong các dòng, ví dụ `/checkout`. |
| **Phát âm thanh khi có tin nhắn mới** | Bật mặc định | Một tiếng chuông ngắn khi có trả lời lúc khung chat đóng hoặc tab đang ẩn. |
| **Nhấp nháy tiêu đề tab khi khách đang ở tab khác** | Bật mặc định | Tiêu đề tab đổi qua lại với "(1) Tin nhắn mới" cho tới khi khách quay lại. |

Việc so khớp là tìm chuỗi con trong toàn bộ URL, và widget kiểm tra lại khi ứng dụng một trang (SPA) đổi URL. Khung chat đang mở thì vẫn hiện.

## Thời gian trực

| Cài đặt | Giá trị | Ghi chú |
|---|---|---|
| **Dùng giờ làm việc** | Tắt mặc định | Không đặt giờ làm việc thì widget trực tuyến bất cứ khi nào có ít nhất một nhân viên trực tuyến. |
| **Múi giờ** | Tên IANA, mặc định `Asia/Ho_Chi_Minh` | |
| Ngày và giờ | Một khung giờ mỗi ngày, mặc định 09:00 đến 18:00 | Tích những ngày làm việc. |
| **Ngày nghỉ** | Ngày dạng `YYYY-MM-DD`, cách nhau bằng dấu phẩy, tối đa 60 | Coi như nghỉ cả ngày. |
| **Khi không ai trực tuyến** | **Hỏi email của khách trước tin nhắn đầu tiên** (mặc định), **Hỏi, nhưng cho phép bỏ qua**, **Chỉ nhận tin nhắn** | Cách widget xử lý khi khách nhắn lúc bạn ngoại tuyến. |
| **Tự xử lý xong hội thoại không hoạt động sau** | 0–365 ngày, mặc định 3; 0 = không bao giờ | Áp dụng cho mọi kênh của website này, trừ nhóm Zalo cá nhân. Khách nhắn lại thì hội thoại mở lại và được phân phối theo quy tắc hiện tại. |
| **Ẩn hẳn bong bóng khi ngoại tuyến** | Tắt mặc định | Khách đã có hội thoại vẫn thấy widget. |
| **Gửi email bản ghi hội thoại cho khách khi xử lý xong** | Tắt mặc định | Cần email của khách. |
| **Cho phép widget trong iframe khác origin** | Tắt mặc định | Mặc định widget không chạy trong iframe khi trang cha có origin khác. |
| **Báo tin nhắn ngoại tuyến mới tới các email này** | Tối đa 20 địa chỉ, cách nhau bằng dấu phẩy | |
| **Gửi email chat từ** | Địa chỉ thuộc tên miền đã xác minh trong Email; trống = người gửi của nền tảng | Địa chỉ người gửi của các email chat gửi cho khách. |

### Widget xác định trực tuyến thế nào

Widget hiện **trực tuyến** khi:

- [Trợ lý AI](https://hatang.dev/vi/docs/guides/support/ai-assistant.md) đang trả lời khách (chế độ "khi ngoại tuyến" hoặc "trả lời đầu tiên"), hoặc
- đang trong giờ làm việc (hoặc không đặt giờ làm việc) **và** có ít nhất một nhân viên trực tuyến.

Ngoài ra là **ngoại tuyến**. Tin nhắn vắng mặt hiện trên đầu khung chat, đầu khung báo giờ quay lại, và khách chưa có email (hoặc chưa để lại số điện thoại ở form trước khi chat) được hỏi email theo mục **Khi không ai trực tuyến**. Với **Hỏi, nhưng cho phép bỏ qua**, khách bấm được Bỏ qua. Chế độ của trợ lý AI đặt cho cả doanh nghiệp ở **Hỗ trợ → Trợ lý AI**.

## Tab Tự động hoá

Tab **Tự động hoá** của site gồm:

- **Nhắc lại khi khách im lặng**: câu cố định hoặc câu do AI viết, gửi khi tin nhắn cuối của đội không được trả lời.
- **Thông báo social proof**: thông báo kiểu "Hùng N. vừa đặt Áo thun" cạnh nút chat, lấy từ đơn đã thanh toán 14 ngày qua hoặc danh sách tự nhập.
- **Đánh giá hài lòng (CSAT)**: chấm sao trong widget khi hội thoại được xử lý xong.
- **Theo dõi chuyển đổi**: sự kiện bắt đầu chat, khách tiềm năng và mua hàng tới hệ thống phân tích của bạn. Xem [JavaScript API](https://hatang.dev/vi/docs/guides/support/web-widget/javascript-api.md#conversion-tracking).
- Danh sách luồng và chiến dịch đang chạy trên site.

Các mục này được giải thích ở [Tự động hoá](https://hatang.dev/vi/docs/guides/support/automation.md).

## Mã bí mật định danh và xoá site

- **Mã bí mật định danh**: để backend của bạn ký các lời gọi `identify`. Xem [Nhận diện khách](https://hatang.dev/vi/docs/guides/support/web-widget/identity-verification.md).
- **Xoá site**: xoá vĩnh viễn site cùng hội thoại, khách truy cập, kênh mạng xã hội đã kết nối và app key. Muốn giữ lịch sử, chuyển **Trạng thái** sang **Đã tắt (ẩn widget)**.

## Ghi đè theo trang bằng `window.HATANG_CONFIG`

Đặt `window.HATANG_CONFIG` trước thẻ script của widget để đổi một vài thứ trên một trang hoặc một phần website. Cài đặt trong dashboard vẫn áp dụng cho phần còn lại.

```html
<script>
  window.$hatang = window.$hatang || [];
  window.HATANG_SITE_ID = "site_123...";
  window.HATANG_CONFIG = {
    position: "left",
    locale: "vi",
    hideLauncher: false,
    offset: { bottom: 24, side: 24 },
    mobileOffset: { bottom: 80, side: 16 }
  };
</script>
<script src="https://chat.hatang.dev/widget.js" async></script>
```

| Khoá | Kiểu | Tác dụng |
|---|---|---|
| `position` | `"left"` hoặc `"right"` | Ghi đè **Vị trí**. |
| `locale` | `"vi"` hoặc `"en"` | Ngôn ngữ ban đầu, trừ khi trang đã gọi `setLocale` trước đó. Ghi đè **Ngôn ngữ mặc định**. |
| `hideLauncher` | `boolean` | Ẩn nút chat. Tự mở chat bằng lệnh `open` hoặc phần tử có `data-hatang-open`. |
| `offset` | `{ bottom?: number, side?: number }` | Khoảng cách từ nút chat tới góc, tính bằng px (giới hạn 0–400). Ghi đè từng giá trị **Desktop: dưới** / **Desktop: cạnh**. |
| `mobileOffset` | `{ bottom?: number, side?: number }` | Như trên, cho màn hình rộng từ 640px trở xuống. Ghi đè **Điện thoại: dưới** / **Điện thoại: cạnh**. Không có thì điện thoại dùng `offset`. |

Cấu hình này chỉ được đọc một lần khi widget khởi động. Muốn đổi sau đó, dùng [JavaScript API](https://hatang.dev/vi/docs/guides/support/web-widget/javascript-api.md) (`setLocale`, `hide`, `show`).

> **Note**
>
> Với `@hatang/chat-react`, truyền cùng object này vào prop `config` của `<HatangChat />`. Với plugin WordPress, mục **Position** và **Language** trong cài đặt plugin tự ghi `position` và `locale`.

## Bước tiếp theo

- [JavaScript API](https://hatang.dev/vi/docs/guides/support/web-widget/javascript-api.md): lệnh và sự kiện cho nút và hệ thống phân tích của bạn.
- [Nhận diện khách](https://hatang.dev/vi/docs/guides/support/web-widget/identity-verification.md): bỏ qua form trước khi chat với người dùng đã đăng nhập và nối lịch sử của họ.
- [Tự động hoá](https://hatang.dev/vi/docs/guides/support/automation.md): nhắc lại, chiến dịch và quy tắc phân phối.

Source: https://hatang.dev/vi/docs/guides/support/web-widget/configuration