# Plugin WordPress Hạ Tầng Chat

Plugin Hạ Tầng Chat thêm widget chat Hạ Tầng vào mọi trang của website WordPress, để đội của bạn trả lời khách trên website trong cùng hộp thư với Zalo, Messenger, Instagram, TikTok, WhatsApp, Telegram và email. Plugin nạp đúng [widget web](https://hatang.dev/vi/docs/guides/support/web-widget/javascript-api.md) qua `wp_enqueue_script` và thêm cài đặt vị trí, ngôn ngữ và người dùng đã đăng nhập.

> **Info: Phiên bản**
>
> Plugin **0.2.1** · WordPress 6.0+ · PHP 7.4+ · GPLv2 trở lên · [wordpress.org](https://wordpress.org/plugins/hatang-chat/) · [Changelog](#changelog)

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

- Một tài khoản Hạ Tầng có kênh website. Bạn cần **Site ID** (`site_...`) của nó: trong dashboard, mở **Hỗ trợ → Kênh**, chọn website và chép id trong đoạn mã cài đặt.
- Một tài khoản WordPress quản lý được plugin và cài đặt (quản trị viên).

## Cài plugin {#install}

1. Trong WordPress, vào **Plugins → Add New**, tìm "Hạ Tầng Chat", cài rồi kích hoạt. Bạn cũng có thể tải tệp zip của plugin lên qua **Plugins → Add New → Upload Plugin**.
2. Vào **Settings → Hạ Tầng Chat**, dán **Site ID** rồi bấm **Save Changes**.
3. Mở một trang bất kỳ của website. Bong bóng chat xuất hiện, và website trong dashboard Hạ Tầng hiện trạng thái đã cài.

Widget chỉ tải ở phía công khai của website, không bao giờ trong wp-admin. Khi Site ID còn trống, plugin không tải gì.

## Cài đặt {#settings}

Mọi cài đặt nằm ở **Settings → Hạ Tầng Chat** và được lưu trong một option là `hatang_chat`. Bảng dưới dùng nhãn tiếng Việt mà trang cài đặt hiện khi ngôn ngữ quản trị là tiếng Việt.

| Cài đặt | Giá trị | Mặc định |
|---|---|---|
| Site ID | Id của website trong dashboard Hạ Tầng | trống (tắt widget) |
| Máy chủ widget | Nơi tải `widget.js` | `https://chat.hatang.dev` |
| Vị trí | Góc dưới bên phải, Góc dưới bên trái | Góc dưới bên phải |
| Ngôn ngữ | **Theo ngôn ngữ WordPress (từng trang)**, **Theo ngôn ngữ trình duyệt của khách**, **Tiếng Việt**, **English** | Theo ngôn ngữ WordPress (website cài từ trước 0.2.0 giữ ngôn ngữ trình duyệt) |
| Người dùng đã đăng nhập | "Gửi tên và email của người dùng vào hộp thư" | Bật |

- **Theo ngôn ngữ WordPress** đọc ngôn ngữ của trang đang được phục vụ (`determine_locale()`), nên chạy đúng từng trang với Polylang và WPML. Locale bắt đầu bằng `vi` cho tiếng Việt; mọi locale khác cho tiếng Anh.
- **Theo ngôn ngữ trình duyệt** để widget tự chọn: theo trình duyệt của khách, hoặc ngôn ngữ mặc định đặt cho site trong dashboard Hạ Tầng.
- Mọi thứ khác (màu, giờ làm việc, lời chào, form offline) lấy từ cài đặt website trong dashboard Hạ Tầng. Với tuỳ chọn mà plugin không có, như `offset` hay `hideLauncher`, tự thêm `window.HATANG_CONFIG` trước script widget, hoặc dùng [JS API](https://hatang.dev/vi/docs/guides/support/web-widget/javascript-api.md) trong theme.

## Người dùng đã đăng nhập {#identify}

Khi bật **Người dùng đã đăng nhập**, plugin gọi `identify` cho khách đã đăng nhập với tên hiển thị và email WordPress. Hộp thư coi đó là thông tin khách tự khai, không phải danh tính đã xác minh.

Để hộp thư đánh dấu người dùng là **đã xác minh** và gộp hội thoại với các phiên trước của cùng người (kể cả trong ứng dụng di động), trả về chữ ký từ filter `hatang_chat_identity_hash`. Chữ ký là HMAC-SHA256 của user id WordPress với identity secret của site. Lấy secret trong dashboard Hạ Tầng: **Hỗ trợ → Kênh** → chọn website → **Mã bí mật định danh** → **Tạo mới & hiển thị**. Giữ nó trong `wp-config.php`, đừng để trong tệp theme mà người khác đọc được.

```php title="wp-config.php"
define( 'HATANG_IDENTITY_SECRET', 'identity-secret-cua-ban' );
```

```php title="functions.php"
add_filter( 'hatang_chat_identity_hash', function ( $hash, $user ) {
    return hash_hmac( 'sha256', (string) $user->ID, HATANG_IDENTITY_SECRET );
}, 10, 2 );
```

Khi filter trả về giá trị, plugin thêm `userId` (user id WordPress dạng chuỗi) và `hash` vào lệnh `identify`. Ý nghĩa của chữ ký, cách gộp phiên và lưu ý riêng tư ở [Nhận diện khách](https://hatang.dev/vi/docs/guides/support/web-widget/identity-verification.md).

## Filter cho lập trình viên {#filters}

| Filter | Tham số | Giá trị trả về |
|---|---|---|
| `hatang_chat_locale` | `$locale` (`"vi"`, `"en"` hoặc `null`), `$setting` (`"wp"`, `""`, `"vi"` hoặc `"en"`) | `"vi"`, `"en"`, hoặc `null` để widget tự chọn |
| `hatang_chat_identity_hash` | `$hash` (`null`), `$user` (`WP_User`) | Chuỗi hex HMAC-SHA256, hoặc `null` cho danh tính chưa xác minh |

Ép tiếng Anh trên một trang, bất kể cài đặt:

```php title="functions.php"
add_filter( 'hatang_chat_locale', function ( $locale, $setting ) {
    return is_page( 'en' ) ? 'en' : $locale;
}, 10, 2 );
```

## Plugin gửi gì tới Hạ Tầng {#data}

Script widget được tải từ `chat.hatang.dev` trên các trang công khai của website. Khi khách mở một trang, nó gửi URL và tiêu đề trang, ngôn ngữ trình duyệt của khách và, nếu bạn bật, tên và email của người dùng đã đăng nhập. Xem [Điều khoản](https://hatang.dev/legal/terms) và [Chính sách quyền riêng tư](https://hatang.dev/legal/privacy).

## Bản dịch trang quản trị {#translation}

Trang cài đặt có bản tiếng Việt (`languages/hatang-chat-vi.po`). WordPress tự chọn bản dịch theo ngôn ngữ quản trị.

## Gỡ bỏ {#uninstall}

Huỷ kích hoạt rồi xoá plugin trong **Plugins**. Plugin không có bước dọn dẹp khi gỡ, nên cài đặt vẫn nằm trong option `hatang_chat`; xoá bằng `wp option delete hatang_chat` nếu muốn cơ sở dữ liệu sạch. Hội thoại vẫn nằm trong tài khoản Hạ Tầng cho đến khi bạn xoá ở đó.

## Changelog {#changelog}

- **0.2.3**: link tác giả trỏ về hatang.dev; readme dẫn tới hướng dẫn cài đặt và hướng dẫn cho lập trình viên này, và trả lời những hội thoại nào dùng chung hộp thư.
- **0.2.2**: plugin đổi tên thành Ha Tang Chat (Hạ Tầng trong tiếng Việt); trang chủ plugin là bài trợ giúp hatang.dev/vi/help/integrations/wordpress; trang cài đặt và readme gọi đúng **Hỗ trợ khách hàng → Kênh**.
- **0.2.1**: trang cài đặt và readme trỏ tới **Hỗ trợ → Kênh**, nơi dashboard Hạ Tầng giờ liệt kê các website; readme liệt kê mọi kênh dùng chung hộp thư.
- **0.2.0**: ngôn ngữ có thể theo ngôn ngữ WordPress của từng trang (chạy với Polylang và WPML); filter mới `hatang_chat_locale`; trang cài đặt có bản tiếng Việt.
- **0.1.1**: nạp widget qua `wp_enqueue_script`.
- **0.1.0**: bản đầu tiên: đoạn mã widget, cài đặt vị trí và ngôn ngữ, nhận diện người dùng đã đăng nhập.

## Bước tiếp theo

- [Widget web và JS API](https://hatang.dev/vi/docs/guides/support/web-widget/javascript-api.md): lệnh, sự kiện và `HATANG_CONFIG`.
- [Nhận diện khách](https://hatang.dev/vi/docs/guides/support/web-widget/identity-verification.md): danh tính có chữ ký và gộp phiên.
- [Cài widget](https://hatang.dev/vi/docs/guides/support/web-widget/install.md): nền tảng khác, hoặc WordPress không dùng plugin.

Source: https://hatang.dev/vi/docs/guides/integrations/wordpress