# Zalo Bot — Gửi tin: chọn nhóm + @tag tên

Cách gọi bot để **gửi vào nhóm nào** và **tag tên kiểu gì**. Không gắn với task LMS.

Bot phải đang chạy (`pm2` / `npm start`). Chi tiết tạo bot: [`zalo-bot.md`](zalo-bot.md).

---

## 1. Một request = một tin

```
POST http://127.0.0.1:3910/send
Header: X-Api-Key: lms-zalo-secret
Content-Type: application/json

{
  "group": "tên nhóm trên Zalo",
  "tags": ["Tên A", "Tên B"],
  "message": "dòng 1\ndòng 2"
}
```

Kết quả trong nhóm: **một** tin, phía trên là thẻ @tag xanh (nếu tag được), bên dưới là nội dung nhiều dòng.

Thứ tự bot làm:

```
1. Tìm nhóm theo `group` (ô search Zalo Web)
2. Mở conversation
3. Với mỗi tên trong `tags`: gõ @ + tên → chọn menu mention → space
4. Gõ `message` (xuống dòng = Shift+Enter)
5. Enter một lần → gửi
```

---

## 2. Gửi vào group nào?

Nhóm được chọn bằng **tên hiển thị trên Zalo** (ô tìm kiếm bên trái), không dùng ID nhóm.

### Thứ tự ưu tiên

1. Field `group` trong body `/send`
2. Nếu trống → `ZALO_GROUP_NAME` của process bot (`ecosystem.config.cjs` / env)

Trong `server.js`:

```js
const group = (req.body.group || CONFIG.groupName || '').trim();
```

`CONFIG.groupName` mặc định `process.env.ZALO_GROUP_NAME || 'placementtest_lcms'`.

### Lấy đúng tên nhóm

Trên Zalo (app hoặc Web): mở nhóm → copy **đúng** tên header (khoảng trắng, dấu, viết hoa).

Ví dụ nhóm hiện tại: `placementtest_lcms`.

Sai một ký tự → search ra nhóm khác hoặc không mở được chat.

### Đổi nhóm mặc định (mọi request không gửi `group`)

Sửa `scripts/zalo-bot/ecosystem.config.cjs`:

```js
ZALO_GROUP_NAME: 'Tên nhóm mới',
```

Rồi:

```bash
cd /var/www/html/lms_hocmai/scripts/zalo-bot
npm run pm2:restart
```

### Đổi nhóm theo từng lần gửi (không restart bot)

Truyền `group` trong body:

```bash
# Nhóm A
curl -s -X POST http://127.0.0.1:3910/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: lms-zalo-secret" \
  -d '{"group":"placementtest_lcms","message":"hello nhóm A"}'

# Nhóm B
curl -s -X POST http://127.0.0.1:3910/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: lms-zalo-secret" \
  -d '{"group":"Tên nhóm B","message":"hello nhóm B"}'
```

Tài khoản Zalo đã login QR **phải là thành viên** nhóm đó. Bot không join nhóm giúp.

### Bot tìm nhóm thế nào (`openGroupChat`)

1. Click ô search (`#contact-search-input` / placeholder “Tìm”).
2. Xóa text cũ, gõ `groupName`, nhấn Enter.
3. Click kết quả đầu (`.conv-item` / `.chat-list-item`).

Nếu nhiều nhóm tên gần giống nhau, kết quả **đầu tiên** được mở — đặt tên nhóm đủ khác biệt.

---

## 3. Tag tên kiểu gì?

`tags` là **mảng tên hiển thị Zalo trong nhóm**, không phải username, không phải `@Tên` sẵn trong string.

```json
"tags": ["Kien dtt", "Tran Thanh Tung"]
```

Bot **không** tag nếu bạn viết `@Kien dtt` trong `message`. Phải đưa tên vào `tags`.

### Kết quả trong ô chat

Với `tags: ["Kien dtt", "Tran Thanh Tung"]` và `message: "hello"`:

```
[Kien dtt] [Tran Thanh Tung] hello
```

`[Kien dtt]` là **thẻ mention xanh** (người đó được notify), không phải text thường `@Kien dtt`.

Nhiều dòng:

```json
{
  "group": "placementtest_lcms",
  "tags": ["Nguyễn Anh Tú"],
  "message": "tt: có việc cần xem\nLink: https://example.com"
}
```

Trong nhóm:

```
[Nguyễn Anh Tú] tt: có việc cần xem
Link: https://example.com
```

Tag nằm **đầu tin**, rồi mới tới nội dung. Xuống dòng trong `message` dùng `\n`.

Không tag: `"tags": []` hoặc bỏ field `tags` → chỉ gửi text.

### Bot tag thế nào (`tagPerson`) — giống gõ tay

Với mỗi tên:

1. Focus ô nhập tin.
2. Gõ `@` → Zalo mở menu mention.
3. Gõ đúng chuỗi tên (vd `Kien dtt`) để Zalo lọc.
4. Click item đầu trong menu (hoặc ArrowDown + Enter) → thành **thẻ xanh**. Enter lúc này **không gửi tin**.
5. Gõ space, rồi tag người tiếp theo.

Code: `sendGroupMessageWithTags` → loop `tagPerson` → `typeMultilineMessage` → `Enter`.

Tên trùng trong mảng bị lọc unique.

### Lấy đúng tên để tag

Trong nhóm Zalo: gõ `@` → copy **đúng** tên hiện trong list (kể cả khoảng trắng / dấu).

Ví dụ đúng với config hiện tại:

| Người | Tên đưa vào `tags` |
|---|---|
| Kiên | `Kien dtt` |
| Tùng | `Tran Thanh Tung` |
| Tú | `Nguyễn Anh Tú` |

Sai ví dụ: `"Kiên"`, `"kien dtt"`, `"Tùng Trần"` → menu lọc sai hoặc không hiện → tin vẫn gửi nhưng **không phải mention thật** (hoặc tag nhầm người đầu list).

### Ví dụ curl có tag

```bash
curl -s -X POST http://127.0.0.1:3910/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: lms-zalo-secret" \
  -d '{
    "group": "placementtest_lcms",
    "tags": ["Kien dtt", "Tran Thanh Tung"],
    "message": "Ping hai người\nXem giúp tin này"
  }'
```

Tag 1 người, nhóm khác:

```bash
curl -s -X POST http://127.0.0.1:3910/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: lms-zalo-secret" \
  -d '{
    "group": "Tên nhóm khác",
    "tags": ["Nguyễn Anh Tú"],
    "message": "hello"
  }'
```

---

## 4. Gọi từ Laravel (optional)

`ZaloNotifyService::send($message, $tags, $group)` POST cùng payload.

```php
app(\App\Services\ZaloNotifyService::class)->send(
    "Nội dung tin\nDòng 2",
    ['Kien dtt', 'Tran Thanh Tung'],  // tags
    'placementtest_lcms'              // group; null = config zalo.group_name
);
```

`$group === null` → `config('zalo.group_name')` ← env `ZALO_GROUP_NAME`.

`.env` Laravel nên **cùng tên nhóm / cùng API key** với bot:

```env
ZALO_BOT_API_URL=http://127.0.0.1:3910
ZALO_BOT_API_KEY=lms-zalo-secret
ZALO_GROUP_NAME=placementtest_lcms
```

---

## 5. Checklist

**Nhóm**

- [ ] Tên `group` copy từ header nhóm Zalo
- [ ] Acc đã QR login là member nhóm
- [ ] Nhiều nhóm tên giống → đổi tên cho khác biệt (bot click kết quả đầu)

**Tag**

- [ ] Tên trong `tags` copy từ list `@` trong **đúng nhóm đó**
- [ ] Không nhét `@Tên` vào `message`
- [ ] Một người một string; nhiều người = nhiều phần tử mảng

**Gửi**

- [ ] Bot `GET /health` → `ready: true`
- [ ] Header `X-Api-Key` khớp bot
- [ ] Fail → `scripts/zalo-bot/debug_error.png` và `pm2 logs zalo-bot`