# Combot Automation Compact v3: hướng dẫn cho LLM và tài liệu định dạng

Đưa toàn bộ tệp này cho mô hình cùng yêu cầu tạo quy tắc. Tệp mô tả định dạng mà trình chỉnh sửa Automation nhập được. Ngôn ngữ quy tắc là JSON Compact v3, không phải Python, YAML, JavaScript, Triggers v2 cũ hay mã giả “nếu → thì” tùy ý.
Tên mục trên giao diện được dịch, còn giá trị JSON thì không. Ví dụ, `Known Combot links` tương ứng với “Liên kết mời Combot”, còn `Combot custom admins` tương ứng với “Quản trị viên Combot” trong trình chỉnh sửa. Không thay các giá trị JSON này bằng tên mục trên giao diện.

Cập nhật tài liệu: ngày 9 tháng 9 năm 2026. Tài liệu đã được đối chiếu với trình chỉnh sửa và bộ xử lý Automation. Các kiểm tra nhập và Telegram đã hoàn tất được liệt kê riêng ở cuối: xem mã nguồn không xác định được phiên bản dịch vụ đang chạy.

## 1. Hướng dẫn cho mô hình

Chuyển yêu cầu của người dùng thành quy tắc Automation mà không thay đổi ý nghĩa.

1. Xác định sự kiện, điều kiện, loại trừ, hành động, người nhận hành động và nơi nhận phản hồi. Với lịch, xác định múi giờ; với lệnh, xác định gửi độc lập hay trả lời tin nhắn. Không thêm kiểm duyệt, phần thưởng, ngẫu nhiên hoặc xóa nếu không được yêu cầu.
2. Không đoán ID người dùng, chủ đề, địa chỉ nhóm, lời mời, cấp bậc hoặc tính năng đang bật. Tên chủ đề không phải ID. Hỏi khi thiếu thông tin thiết yếu. Có thể đề xuất riêng cách viết phản hồi, nhưng không trình bày quy tắc chưa đầy đủ như lời giải chính xác.
3. Luôn tạo quy tắc mới với `en: false`. Đây là quy ước chuẩn bị an toàn, không phải giới hạn của Automation. Bỏ `en` nghĩa là bật.
4. Chỉ dùng trường đã được mô tả. Với bộ lọc lồng nhau có ghi “dùng bản xuất”, yêu cầu bản xuất thật của cấu hình tương tự; không tự nghĩ ra cấu trúc. Nếu tình huống không được hỗ trợ, giải thích giới hạn thay vì che giấu bằng cách bỏ điều kiện.
5. Trả lời theo thứ tự: giải thích ngắn → một khối JSON nhập được → cài đặt và kiểm tra thủ công. JSON không được có chú thích, dấu ba chấm, ID giữ chỗ, dòng giải thích ngoài trường, dấu phẩy cuối hoặc khóa tự đặt như `when`, `if`, `then`, `conditions`, `actions` hay `event`.
6. Trước khi trả kết quả, suy xét một trường hợp khớp và một trường hợp không khớp. Với lệnh trả lời, kiểm tra người gửi lệnh riêng với tác giả tin nhắn gốc. Không nói đã thử quy tắc trong Combot nếu chưa thực sự làm.

JSON Schema kèm theo hỗ trợ tạo quy tắc mới đang tắt. Các trường bắt buộc cố ý chặt hơn việc nhập, và lược đồ không chấp nhận mọi bản xuất cũ. Bộ lọc lồng nhau phức tạp chỉ được kiểm tra là đối tượng. Đạt lược đồ không chứng minh điều kiện tương thích, tài nguyên có sẵn, tuân thủ gói hoặc hành động Telegram thành công.

## 2. Nội dung cần dán vào Import

Gốc là đối tượng có số `v: 3` và mảng quy tắc `t`. Thường chỉ trả một quy tắc. Không trả mảng trần hoặc `{"triggers": [...]}`: đó không phải định dạng của hộp thoại nhập.

Ví dụ tối thiểu đầy đủ:

```json
{
  "v": 3,
  "t": [
    {
      "n": "Lệnh thông tin khóa học",
      "en": false,
      "k": "c",
      "ctm": "p",
      "cm": ["/course_info"],
      "a": {
        "m": "a",
        "r": [
          {
            "i": "course_reply",
            "t": "s",
            "v": {
              "tx": "Bản ghi buổi học nằm trong tin nhắn đã ghim của nhóm.",
              "rp": "r"
            }
          }
        ]
      }
    }
  ]
}
```

`dv: "t3.compact.3"` là dấu phiên bản lược đồ tùy chọn. Kết quả mới chỉ cần `v` và `t`. Chức năng nhập hiện nhận lớp bọc `bundle`, nhưng khi tạo không cần dùng.

Không thêm `id` của máy chủ, `revision`, `chat_id`, `ck` được tính hoặc `$schema` vào gói nhập. Máy chủ cấp ID mới cho quy tắc. `i` của hành động khác: đó là mã dòng nội bộ như `course_reply`. Nó phải duy nhất trong các hành động của quy tắc và chứa 1–80 chữ cái Latin, chữ số, `_` hoặc `-`.

Cùng một khóa ngắn có nghĩa khác ở từng cấp: `t` ở gốc là danh sách quy tắc, `a.r[].t` là loại hành động, còn `a.r[].v` chứa tham số hành động. Không trộn các cấp.

## 3. Các trường chính của quy tắc

| Trường | Ý nghĩa |
| --- | --- |
| `n` | Tên không trống, tối đa 80 ký tự trong trình chỉnh sửa |
| `d` | Mô tả tùy chọn, tối đa 280 ký tự trong trình chỉnh sửa |
| `en` | `false` cho quy tắc mới đang tắt |
| `e` | Mảng mã sự kiện, trừ khi đây là lệnh |
| `k`, `cm`, `ctm` | Chế độ lệnh; xem bên dưới |
| `a` | Kế hoạch hành động: `{"m":"a","r":[...]}` hoặc `{"m":"r","r":[...]}` |
| `s`, `ti` | Nơi kiểm tra sự kiện: nhóm nguồn, Chung hoặc chủ đề đã chọn |
| `at` | Khi nào cho phép khớp; bộ lọc thời gian, không phải bộ hẹn giờ |
| `wh`, `wx`, `wm` | Người thực hiện sự kiện: nhóm bao gồm, loại trừ và cách kết hợp nhóm |
| `cgr` | Điều kiện số: thời gian trong nhóm, tin nhắn, cảnh báo, XP, danh tiếng |
| `ua`, `ux`, `uar`, `ul`, `ulx` | Thuộc tính thành viên, giá trị trường và ngôn ngữ |
| `twh`, `twx`, `tcg`, `tua`, `tux`, `tur`, `tlg`, `tlx` | Kiểm tra người còn lại trong sự kiện, như tác giả tin nhắn được trả lời hoặc thành viên vào nhóm |
| `tv`, `tr`, `ty`, `cs`, `lmin`, `lmax` | Điều kiện văn bản |
| `mti`, `mtx`, `me`, `mex` | Loại tin nhắn và thực thể văn bản |
| `il`, `ilc`, `ilx` | Liên kết mời cho yêu cầu tham gia |
| `rct`, `rnt`, `rnx`, `rcy`, `rcx`, `rcn`, `rcm` | Điều kiện phản ứng |
| `chl` | Liên kết trực tiếp đến danh sách cụ thể cho sự kiện thay đổi công việc |
| `cl` | Dọn phản hồi trước mặc định: `n` hoặc `ps` |
| `ov` | Bộ điều kiện HOẶC thay thế; dùng bản xuất cho trường hợp phức tạp |

Không điền mọi trường. Chỉ thêm điều kiện được yêu cầu và phù hợp sự kiện đã chọn. Ví dụ, vào nhóm không cần từ khóa tin nhắn, còn bộ đếm phản ứng tổng hợp không có người dùng cụ thể để tự thưởng.

## 4. Sự kiện

| `e` | Khi nào chạy |
| --- | --- |
| `["m"]` | Tin nhắn nhóm mới |
| `["em"]` | Chỉnh sửa tin nhắn |
| `["m","em"]` | Tin nhắn mới hoặc chỉnh sửa |
| `["lc"]`, `["el"]`, `["lc","el"]` | Bình luận của kênh liên kết, chỉnh sửa hoặc cả hai |
| `["cp"]`, `["ec"]`, `["cp","ec"]` | Bài đăng trong ngữ cảnh kênh liên kết, chỉnh sửa hoặc cả hai |
| `["jr"]` | Yêu cầu tham gia |
| `["nm"]` | Thành viên vào nhóm |
| `["ml"]` | Thành viên rời hoặc bị xóa |
| `["cb"]`, `["rb"]` | Boost được thêm hoặc gỡ |
| `["mr"]` | Phản ứng của một người dùng cụ thể thay đổi |
| `["rc"]` | Bộ đếm phản ứng ẩn danh tổng hợp được cập nhật trong ngữ cảnh kênh liên kết |
| `["ck"]` | Danh sách công việc mới |
| `["cd"]` | Công việc được đánh dấu hoàn tất |
| `["ca"]` | Công việc được thêm vào danh sách |

Không kết hợp loại sự kiện không liên quan như `["m","nm"]`; dùng quy tắc riêng. Các cặp mới và đã sửa được liệt kê ở trên được phép. Không tạo chế độ bot khách ẩn `gm`.

Chỉnh sửa là lần kích hoạt riêng. Không tự thêm nó vào XP, danh tiếng, cảnh báo hoặc hành động mà người dùng mong chỉ xảy ra một lần.

## 5. Lệnh đơn và lệnh trả lời

Lệnh đơn, chẳng hạn phản hồi thông tin:

```json
{"k":"c","ctm":"p","cm":["/course_info"]}
```

Lệnh mà quản trị viên gửi để trả lời tin nhắn thành viên:

```json
{"k":"c","cm":["/team_pause"]}
```

Đây là các đoạn trường quy tắc, không phải gói nhập độc lập.

Không thêm `e` vào lệnh. Cung cấp danh sách không trống các lệnh riêng chữ thường bắt đầu bằng dấu gạch chéo trong `cm`, dùng chữ cái Latin, chữ số và `_`. Không trình bày lệnh tự đặt như lệnh tích hợp của Combot. Với lệnh trả lời, bỏ `ctm`; không viết `reply_target`, `r` hoặc tên người vào đó.

Lệnh đơn không có người nhận cho hành động dành cho người dùng. Dùng gửi tin nhắn và, chỉ khi được yêu cầu rõ, xóa tin nhắn lệnh. Tắt tiếng, cảnh báo, XP và các hành động tác động đến người cần lệnh trả lời.

Trong lệnh trả lời, `wh` kiểm tra người gửi lệnh, còn `twh` và các trường `t...` khác kiểm tra tác giả tin nhắn được trả lời. Dùng `v.tg: "t"` để tác động đến người sau. Nếu An trả lời Minh bằng `/team_pause`, hạn chế Minh, không phải An.

Chỉ kiểm tra `twh` không giới hạn ai được gọi lệnh. Lệnh quản trị phải có `wh` theo yêu cầu. Hành động `d` xóa chính lệnh, không phải tin nhắn của Minh.

Không thay chế độ lệnh bằng tìm chuỗi `/team_pause` trong `tv`. Không thêm điều kiện lệnh bị ẩn trong trình chỉnh sửa, như lịch, khi chưa có bản xuất đã xác minh.

## 6. Thành viên và loại trừ

`wh` và `wx` dùng đúng các chuỗi này, không dùng nhãn dịch:

`New members`, `Regular members`, `Ex-members`, `Whitelisted users`, `Admins`, `Telegram admins`, `Combot custom admins`, `Owner`.

Danh sách bao gồm trống không giới hạn nhóm người dùng. Thường có thể bỏ `Anyone`. `wm: "o"` yêu cầu một nhóm khớp; `wm: "a"` yêu cầu mọi nhóm đã chọn. Loại trừ trong `wx` ngăn khớp bất kể nhóm tích cực.

Ví dụ: bất kỳ ai trừ quản trị viên có thể gửi tin nhắn phù hợp:

```json
{"wx":["Telegram admins","Combot custom admins","Owner"]}
```

Ví dụ: chỉ quản trị viên Telegram hoặc chủ nhóm được gọi lệnh:

```json
{"wh":["Telegram admins","Owner"],"wm":"o"}
```

Không nhầm vai trò. `Combot custom admins` mô tả quyền Combot, không phải quản trị viên Telegram. Trong bộ xử lý, `Admins`, giống `Telegram admins`, kiểm tra quản trị viên Telegram gồm chủ nhóm; nó không thêm quản trị viên Combot. Để cho phép cả hai nhóm, liệt kê `Telegram admins` và `Combot custom admins` với `wm: "o"`. `Regular members` nghĩa là thành viên hiện tại đã biết, không phải người ở lâu hoặc gửi nhiều tin. `New members` dùng cài đặt người mới và miễn trừ hiện có của nhóm; không phải “bảy ngày đầu” cố định. Dùng `cgr` cho thời lượng chính xác.

Không tạo `Core members` hoặc `Non-members`: không có định nghĩa đáng tin được cung cấp cho quy tắc mới. Thiếu thông tin thành viên không chứng minh người đó chưa từng thuộc nhóm.

Với đối tượng, dùng `twh`, `twx` và `twm`. Lấy giá trị ngữ cảnh bổ sung như `Target self`, `Target bots`, `Target Combot` và `Target linked channel post` từ bản xuất phù hợp; không đoán chúng trong bộ lọc người gửi.

Với `nm` và `ml`, `wh`/`wx` mô tả người khởi đầu việc vào hoặc xóa; `twh`/`twx` mô tả thành viên có trạng thái thay đổi. Nếu An thêm Minh, điều kiện người mới thuộc Minh qua `t...`, không phải An. Chọn `v.tg` ở hành động không đổi các điều kiện này.

`am: "o"` kiểm tra quản trị viên Telegram; `am: "n"` loại trừ họ. Đây không phải thay thế cho kết hợp vai trò trong `wh`/`wx`. Ưu tiên nhóm rõ ràng cho quy tắc mới.

## 7. Thời gian trong nhóm, hoạt động, XP và danh tiếng

Điều kiện số nằm trong `cgr`, hoặc `tcg` cho đối tượng. Đoạn này nghĩa là thành viên ở nhóm nhiều nhất một giờ và có nhiều nhất năm tin nhắn được ghi nhận:

```json
{
  "cgr": {
    "logic": "All",
    "statistics": {
      "rules": [
        {"metric":"joinedDays","unit":"h","op":"lte","value":"1"},
        {"metric":"messageCount","unit":"c","join":"and","op":"lte","value":"5"}
      ]
    }
  }
}
```

Phép so sánh: `eq` là bằng, `gte` ít nhất và `lte` nhiều nhất. Luôn ghi rõ phép so sánh. Không dịch “dưới năm” thành `lte: 5`: với bộ đếm số nguyên, đó là `lte: 4`. Không dùng so thời lượng chính xác `eq` khi người dùng muốn “ít nhất”: thời gian vẫn tiếp tục trôi.

Chỉ số thống kê:

- `joinedDays`: thời gian từ khi tham gia nhóm này, không phải tuổi tài khoản hay tuổi người. Đơn vị: `s`, `m`, `h`, `d`, `w`, `mo`. Một ngày là 24 giờ, một tuần là 7 ngày, một tháng ở đây là 30 ngày. Quy tắc mới luôn phải có đơn vị.
- `messageCount`: tin nhắn được ghi nhận trong nhóm này; đơn vị `c`.
- `warns`: cảnh báo đang có hiệu lực; đơn vị `c`.

“Một tin nhắn được ghi nhận” là `{"metric":"messageCount","unit":"c","op":"eq","value":"1"}`. Điều này không đảm bảo thực thi đúng một lần: cập nhật bộ đếm và xử lý sự kiện có thể diễn ra riêng.

Các phần khác:

```json
{
  "cgr": {
    "logic": "All",
    "xp": {
      "xp": {"rules":[{"op":"gte","value":"100"}]}
    },
    "reputation": {
      "reputation": {"rules":[{"op":"gte","value":"5"}]}
    }
  }
}
```

Ngưỡng cấp bậc dùng `cgr.xp.rank.rules`, nhưng giá trị phải lấy từ cấp bậc thật của nhóm, không tự đặt tên. Các dòng hỗ trợ `join: "and" | "or"` và `mode: "include" | "exclude"`. Dùng AND rõ ràng cho điều kiện đơn giản và bản xuất thật cho chuỗi AND/OR phức tạp. `cgr.logic: "All" | "Any"` kết hợp các phần. Dòng số loại trừ là điều cấm: khớp tích cực ở phần khác trong cùng phương án điều kiện không thể vượt qua nó.

Không tạo kiểm tra thời gian từ tin nhắn đầu hoặc hoạt động đầu khác: `firstMessageAge` và `firstOtherActivityAge` không khả dụng. Không hứa “hoạt động tuần trước” bằng tổng `messageCount`. Dữ liệu không có không được tự thành số không.

## 8. Thuộc tính và trường người dùng

`ua` yêu cầu thuộc tính; `ux` loại trừ. Giá trị chính xác: `Any username`, `Telegram Premium`, `Bot account`, `Any last name`. Ví dụ, `{"ux":["Bot account"]}` loại trừ bot.

`ul` và `ulx` bao gồm và loại trừ mã ngôn ngữ người dùng nếu Telegram cung cấp. Đây không phải ngôn ngữ tin nhắn hay quốc tịch. Không suy ngôn ngữ từ tên thành viên.

Điều kiện về giá trị cụ thể nằm trong `uar`, hoặc `tur` cho đối tượng. Trường hỗ trợ: `user_id`, `name`, `username`, `last_name`, `bio`. Giới thiệu thuộc ngữ cảnh yêu cầu tham gia; không phải trường hồ sơ luôn có cho mọi thành viên.

Điều kiện tên người dùng có cấu trúc:

```json
{
  "uar": {
    "username": {
      "rules": [
        {"mode":"include","matchType":"Exact match","values":["example_member"]}
      ]
    }
  }
}
```

Đây là minh họa cấu trúc, không phải thành viên thật. Với yêu cầu thực tế, chỉ dùng tên người dùng do người yêu cầu cung cấp, không có `@`; hỏi nếu thiếu. Cung cấp ID dạng chuỗi trong `values`. Với kiểm soát truy cập, ưu tiên ID được cung cấp rõ: tên và tên người dùng có thể đổi.

Ở đây `matchType` dùng chuỗi đầy đủ `Exact match`, `Partial match` và `Regular expression`, không phải mã văn bản tin nhắn `f`, `p` và `r`. Giá trị trong một dòng là lựa chọn thay thế; các dòng có `join`. Không tự thêm `Starts with` hoặc `Ends with` cho các trường này.

`ual` và `tul`: `a` nghĩa là mọi quy tắc; `o` nghĩa là bất kỳ nhóm nào. Dùng bản xuất cho cấu trúc nhóm `uag` và `tug` trong hồ sơ tạo quy tắc này.

## 9. Văn bản và loại tin nhắn

Dùng `tv`, một mảng chuỗi, để tìm cụm từ. Chỉ cần một chuỗi khớp. Ví dụ:

```json
{"tv":["bản ghi ở đâu","bản ghi buổi học"],"tr":"p","ty":"p","cs":false}
```

`tr`: `p` là cụm từ, `w` là từ và `r` là biểu thức chính quy. Chế độ từ không yêu cầu mọi từ trong danh sách. Khớp một phần thông thường cũng không đảm bảo ranh giới từ: “cat” có thể khớp bên trong “catalog”.

`ty`: `f` là toàn bộ văn bản, `p` là một phần, `s` là đầu, `e` là cuối và `r` là biểu thức chính quy. `cs: true` phân biệt chữ hoa, chữ thường; `false` hoặc bỏ trường sẽ không phân biệt. Câu hỏi thường gặp đơn giản chỉ cần `tv`: mặc định là tìm cụm từ không phân biệt hoa thường.

`lmin` và `lmax` giới hạn độ dài văn bản. Giới hạn trống hoặc bằng không không hạn chế phía đó. Không nhầm độ dài văn bản với số từ.

Chỉ dùng biểu thức chính quy khi khớp đơn giản không đủ. Cung cấp mẫu dưới dạng chuỗi JSON, thoát dấu gạch chéo ngược; không tự thêm dấu bao JavaScript `/.../i`. Với yêu cầu nguyên từ hoặc phủ định phức tạp, giải thích ví dụ khớp và không khớp.

`mti` bao gồm loại tin nhắn; `mtx` loại trừ. Giá trị chính: `photo`, `video`, `animation`, `audio`, `document`, `sticker`, `voice`, `video_note`, `contact`, `location`, `poll`, `dice`, `game`, `paid_media`. Ví dụ, `{"mti":["voice"]}` là tin nhắn thoại; `{"mti":["photo","video"]}` nghĩa là ảnh HOẶC video, không phải hai tệp đính kèm cùng lúc.

Trình chỉnh sửa còn có `text` và `caption`. Chúng tham gia cài đặt nội dung văn bản; không coi `caption` là loại đính kèm Telegram độc lập. Với “chỉ chú thích ảnh” hoặc phân biệt chặt văn bản và chú thích, lấy bản xuất cấu hình đó. Codec có thể bỏ giá trị mặc định, kể cả `text` đơn lẻ; chỉ có giá trị này trong JSON đầu vào không chứng minh hạn chế được giữ sau khi nhập.

`me` và `mex` yêu cầu hoặc loại trừ thực thể văn bản. Giá trị: `bot_command`, `url`, `text_link`, `mention`, `hashtag`, `cashtag`, `email`, `phone_number`, `emoji`, `custom_emoji`, `bold`, `italic`, `underline`, `strikethrough`, `code`, `pre`, `spoiler`, `blockquote`, `expandable_blockquote`. `mel: "a"` yêu cầu mọi thực thể được bao gồm; `"o"` yêu cầu ít nhất một. Cho mọi liên kết hiển thị hoặc ẩn: `{"me":["url","text_link"],"mel":"o"}`.

`mef` thu hẹp liên kết, lệnh và thực thể cụ thể; `mmo` mô tả thuộc tính đa phương tiện; `mtg` và `mog` là nhóm điều kiện; `csx`/`cse` là bộ ký tự. Tạo các trường phức tạp này từ bản xuất thật. Không tự đặt trường thay thế như `max_file_size`, `allowed_domains`, `mime`, `language` hoặc `contains_all`.

## 10. Thời gian và chủ đề nhóm

`s`: `sc` là nhóm nguồn, `gn` là Chung và `st` là chủ đề đã chọn. Với lựa chọn cuối, `ti` chứa ID chủ đề dương.

Nhập đặt chủ đề nguồn đã chọn về toàn bộ nhóm nguồn, còn chủ đề gửi đã chọn về chủ đề hiện tại. Điều này xảy ra ngay cả với ID đúng và áp dụng cả cho phương án HOẶC. Nếu tình huống phụ thuộc chủ đề, nêu tên trong giải thích và cài đặt thủ công bắt buộc. Không gọi kết quả sẵn sàng bật trước khi chọn lại chủ đề.

`at` đặt thời gian sự kiện được phép; không lên lịch gửi độc lập. “Trả lời câu hỏi buổi tối” làm được. “Đăng mỗi ngày lúc 19:00 mà không có sự kiện đến” cần trình lên lịch, không phải trình kích hoạt này.

Bot kiểm tra thời gian hiện tại khi xử lý sự kiện, không phải dấu thời gian tin nhắn gốc. Chỉnh sửa buổi sáng kiểm tra giờ sáng dù tin nhắn gốc được viết ban đêm.

Khung giờ hằng tuần, thứ Hai–thứ Sáu, 09:00–18:00 UTC:

```json
{"at":{"m":"w","wd":[0,1,2,3,4],"tw":[{"startMinute":540,"endMinute":1080}]}}
```

`wd`: 0 là thứ Hai, 6 là Chủ nhật. Giờ là số phút nguyên từ nửa đêm UTC, từ 0 đến 1439. Khung giờ hằng tuần bao gồm phút cuối. Khung qua đêm có thể có đầu lớn hơn cuối; ngày trong tuần dùng ngày UTC hiện tại, không phải ngày bắt đầu “ca”. Kiểm tra hai phía nửa đêm thay vì đoán ngày cần chọn.

09:00 và 18:00 Moskva tương ứng 06:00 và 15:00 UTC: phút 360 và 900. Để ngừng khớp đúng 18:00, phút cuối được phép là 14:59 UTC, tức `endMinute: 899`. Với múi giờ khác, tính độ lệch và khả năng đổi giờ mùa hè. Không nhập giờ địa phương như UTC mà chưa chuyển đổi.

Khoảng ngày:

```json
{"at":{"m":"d","s":"2026-10-01T00:00:00Z","e":"2026-10-07T23:59:59Z"}}
```

Đây là minh họa cấu trúc, không phải ngày chiến dịch của người dùng. Bắt đầu phải trước kết thúc. Chế độ này bao gồm cả hai mốc. `Z` là UTC.

Giờ đóng cửa dùng cài đặt hiện có của nhóm: `{"at":{"m":"c"}}`; ngoài giờ đó: `{"at":{"m":"c","i":true}}`. Chế độ giờ đóng gồm mốc đầu và không gồm mốc cuối. Trình kích hoạt không cấu hình lịch đóng nhóm. Không có lịch hợp lệ thì không hứa điều kiện trực tiếp hoặc đảo ngược hoạt động.

## 11. Liên kết mời, phản ứng và danh sách công việc

### Lời mời

Với yêu cầu tham gia `["jr"]`, `il` nhận `Known Combot links`, `External invite link` hoặc `Any source`. Bỏ trường nếu không cần hạn chế.

`Known Combot links` nghĩa là liên kết trong danh mục Combot của nhóm này. `ilc` và `ilx` liệt kê mã liên kết được bao gồm và loại trừ trong danh mục; lấy mã chính xác từ bản xuất hoặc dữ liệu được cung cấp. Danh sách trống vẫn giữ kiểm tra loại nguồn chung.

`External invite link` nghĩa là liên kết đã xác định nằm ngoài toàn bộ danh mục Combot, không phải “mọi thứ trừ hai liên kết tôi chọn”. Nguồn chưa biết hoặc danh mục không khả dụng không thể được coi là liên kết bên ngoài. Không hứa điều kiện này bắt được mọi yêu cầu không có lời mời đã biết.

### Phản ứng của người dùng

Sự kiện `["mr"]`. `rct` chứa `added` và/hoặc `removed`. `rnt` và `rnx` bao gồm và loại trừ phản ứng trong trạng thái mới của người dùng. Nếu một trong hai có giá trị, `rct` phải có `added`.

Bộ xử lý chỉ chạy `mr` khi Telegram cung cấp `user`. Phản ứng gửi dưới danh nghĩa kênh hoặc quản trị viên ẩn danh với `actor_chat` không kích hoạt sự kiện này. Điều này khác tổng số phản ứng `rc`.

```json
{"e":["mr"],"rct":["added"],"rnt":["👍"]}
```

Giá trị phản ứng là emoji thường, ID emoji tùy chỉnh dạng chuỗi hoặc `paid`. `rnt` kiểm tra toàn bộ trạng thái mới, không chỉ phần thay đổi. Nếu 👍 đã có và người dùng thêm phản ứng khác, điều kiện có thể khớp lại. Người nhận hành động `u` ở đây là người thay phản ứng; nó không tự thưởng tác giả tin nhắn.

### Tổng số phản ứng

Sự kiện `["rc"]`. `rcy`/`rcx` chọn loại phản ứng được đếm. `rcn`/`rcm` đặt giới hạn số lượng dưới và trên bằng số nguyên không âm. Số không hoặc bỏ trường nghĩa là không giới hạn phía đó.

```json
{"e":["rc"],"rcy":["👍"],"rcn":10}
```

Điều này kiểm tra giá trị hiện tại lúc cập nhật, không phải “lần đầu đạt mười”. Cập nhật phù hợp khác có thể chạy lại hành động. Bộ đếm tổng hợp ẩn danh không có người gửi phản ứng cụ thể.

### Danh sách công việc

Với `["cd"]` và `["ca"]`, `chl` giới hạn quy tắc vào một danh sách. Nếu người dùng muốn danh sách cụ thể, hỏi liên kết tin nhắn trực tiếp. Nếu muốn mọi danh sách phù hợp trong nhóm hoặc chủ đề, không thêm `chl`.

Liên kết Telegram trực tiếp, kể cả có số chủ đề, được hỗ trợ; liên kết có `?comment=` thì không. Không tự đặt địa chỉ. Với liên kết công khai, bộ xử lý sự kiện phải biết tên người dùng của nhóm; chỉ URL trông hợp lệ không xác nhận được khớp.

## 12. Hành động

`a.m: "a"` chạy mọi dòng theo thứ tự. `a.m: "r"` chạy mọi dòng đánh dấu `fr: 1` và đúng một dòng không đánh dấu được chọn ngẫu nhiên, nếu có. Các dòng được chọn giữ thứ tự gốc. Dùng chế độ `a` trừ khi được yêu cầu ngẫu nhiên; không thêm `fr` ngoài chế độ ngẫu nhiên.

| Mã `a.r[].t` | Hành động | Tham số `v` |
| --- | --- | --- |
| `s` | Gửi tin nhắn | `tx` và định dạng; xem dưới |
| `d` | Xóa tin nhắn đã kích hoạt quy tắc | Không có tham số |
| `w` | Thêm cảnh báo | `tg`, `c` dương, thường là 1 |
| `rw` | Gỡ cảnh báo | `tg`, `c` dương, thường là 1 |
| `m` | Hạn chế nhắn tin | `tg`, thời lượng `du` tính bằng giây |
| `b` | Cấm | `tg`, thời lượng `du` tính bằng giây |
| `k` | Xóa khỏi nhóm nhưng cho phép vào lại | `tg` |
| `um` | Gỡ hạn chế nhắn tin | `tg` |
| `ub` | Gỡ cấm | `tg` |
| `du` | Xóa tin nhắn người dùng đã lưu mà bot có | `tg` |
| `x` | Thay đổi XP | `tg`, số nguyên `v` khác không từ −99999 đến 99999 |
| `r` | Thay đổi danh tiếng | `tg`, số nguyên `v` khác không từ −999 đến 999 |
| `ja` | Chấp thuận yêu cầu tham gia | Chỉ sự kiện `jr`, không có tham số |
| `jd` | Từ chối yêu cầu tham gia | Chỉ sự kiện `jr`, không có tham số |

Không nhầm mã hành động `du` với trường thời lượng `v.du`. Thời lượng tính bằng giây, không phải phút: một giờ là 3600. Số không cho tắt tiếng hoặc cấm nghĩa là không có thời điểm kết thúc; không bao giờ dùng thay thời lượng chưa biết. Có thể viết lý do trong tin nhắn riêng nếu được yêu cầu; không hứa lý do xử phạt tùy chỉnh qua trường không được mô tả.

Người nhận hành động người dùng `v.tg`:

- `u`: người gây ra sự kiện.
- `t`: đối tượng theo ngữ cảnh, như tác giả tin nhắn được trả lời. Không phải ID trực tiếp.
- `l`: người tạo liên kết mời trong danh mục Combot, ở ngữ cảnh yêu cầu tham gia.
- `b`: cả hai người có sẵn trong ngữ cảnh tương ứng. Không phải “mọi người trong nhóm”.

Luôn chỉ rõ người nhận. Lệnh đơn không hỗ trợ hành động người dùng. Lệnh trả lời hỗ trợ người gửi, đối tượng và cả hai. Với yêu cầu tham gia, dùng hành động riêng cho người xin vào (`u`) và người tạo liên kết đã biết (`l`) nếu cần cả hai: `b` không có nghĩa người xin vào cộng người tạo liên kết. Trình chỉnh sửa có lựa chọn người tạo liên kết cho yêu cầu tham gia; không đưa cùng lựa chọn vào hướng dẫn từng bước cho sự kiện thành viên đã vào. Với sự kiện khác, chỉ dùng người nhận có trong sự kiện đó.

Đối tượng chưa biết không được biến hành động thành hình phạt cho người gửi lệnh. Không hứa chuyển sang người khác. Hành động `du` không đảm bảo xóa toàn bộ lịch sử thành viên: bot bị giới hạn bởi tin nhắn có sẵn và khả năng Telegram.

Cảnh báo, cấp độ và danh tiếng phải được bật khi tình huống phụ thuộc vào chúng; kiểm duyệt cần quyền phù hợp của bot. Bỏ tắt tiếng, bỏ cấm và chấp thuận yêu cầu tham gia là hành động riêng.

Sự kiện yêu cầu tham gia cho phép gửi tin nhắn, hành động lên người có sẵn và `ja`/`jd`; xóa tin nhắn `d` không phù hợp. Với sự kiện không có tin nhắn, không thêm xóa hoặc trả lời một tin nhắn không tồn tại.

## 13. Văn bản và nơi nhận phản hồi

Tham số hành động `s`:

| Trường | Ý nghĩa |
| --- | --- |
| `tx` | Văn bản không trống, tối đa 4096 ký tự; được dùng HTML Telegram hỗ trợ |
| `d` | `sc`: nhóm nguồn; `lg`: kênh nhật ký đã cấu hình; mặc định `sc` |
| `tp` | `ct`: chủ đề hiện tại; `gn`: Chung; `st`: chủ đề đã chọn; mặc định `ct` |
| `to` | ID chủ đề đã chọn dạng số dương; bị đặt lại khi nhập |
| `rp` | `r`: trả lời tin nhắn kích hoạt; bỏ trường: tin nhắn độc lập |
| `cl` | `n`: giữ phản hồi trước; `ps`: xóa phản hồi trước của dòng này |
| `bt` | Các hàng nút URL: mảng các mảng đối tượng có `text` và `url` |
| `ph` | Mảng URL ảnh cho xem trước liên kết |
| `pa` | `true`: đặt bản xem trước lên trên văn bản |

`rp: "r"` được giữ cho nhóm nguồn và chủ đề hiện tại. Không hứa giữ cùng liên kết trả lời ở nhật ký hoặc chủ đề khác. Không đặt nhóm ngoài tùy ý, kênh hoặc tin nhắn riêng trong `d`.

Nếu dòng không có `cl`, nó kế thừa cài đặt quy tắc. `cl: "ps"` ở quy tắc bật dọn phản hồi trước; `cl: "n"` rõ ràng ở dòng ghi đè. Dọn dẹp thuộc về quy tắc, dòng hành động và nơi nhận cụ thể. Các dòng ngẫu nhiên khác nhau không trở thành một “lời chào cuối” dùng chung.

Với phản hồi thường, có thể dùng `<b>Thông tin khóa học</b>\nBản ghi nằm trong tin nhắn đã ghim.` Không đưa Markdown như HTML. Thoát liên kết và văn bản đúng cách. Chỉ thêm nút và ảnh với URL thật do người yêu cầu cung cấp; `ph` không gửi album ảnh.

Các biến đã xác nhận trong ngữ cảnh tin nhắn: `{name}`, `{uid}`, `{name_link}`, `{from.id}`, `{from.title}`, `{from.username}`, `{chat.id}`, `{chat.title}`, `{chat.username}`, `{message.id}`, `{message.timestamp}`, `{timestamp}`, `{group_name}`, `{reply_to_uid}`, `{reply_to_name}`, `{reply_to_name_link}`. Khả năng có dữ liệu tùy sự kiện. Không tự đặt `{target.name}`, `{user.first_name}`, `{reaction_count}` hoặc biến tương tự.

Trong lệnh trả lời, `{from.title}` mô tả người gửi lệnh, không phải thành viên bị phạt hoặc nhận thưởng. Chọn `tg: "t"` không đổi nghĩa biến. Nếu không chắc sự kiện cung cấp tên cần dùng, viết trung tính.

Khi vào nhóm, `{from.title}` cũng không đảm bảo tên người mới: nếu An thêm Minh, An là người thực hiện. Dùng lời chào chung như “Chào mừng bạn đến với {chat.title}!” không kèm tên người.

Hành động không phải giao dịch nguyên khối. Tin nhắn sau hành động tắt tiếng không chứng minh Telegram đã áp dụng tắt tiếng. Không viết xác nhận xử phạt vô điều kiện như kết quả đã xác minh: ở đây không có điều kiện kiểm tra thành công riêng được mô tả.

## 14. Phương án, giới hạn và những điều không thể hứa

`ov` chứa điều kiện thay thế cho cùng quy tắc. Chúng dùng chung sự kiện và hành động của quy tắc chính, không định nghĩa tình huống độc lập. Loại trừ trong một phương án không có hiệu lực toàn cục. Nếu điều cấm phải luôn áp dụng, giữ nó trong mọi phương án. Phương án có `en: false` không tham gia so khớp.

Dùng bản xuất thật từ trình chỉnh sửa cho `ov`, `mtg`, `mog`, `uag`, `tug`, `mef` và `mmo` phức tạp mới. Không tạo cây OR đệ quy hoặc đặt chuỗi hành động riêng trong phương án rồi mong chúng chạy độc lập.

Các trường tương thích `mt`, `mtl`, `t`, `rmi` và `rme` có thể xuất hiện trong bản xuất. Không thêm chúng thay cài đặt chính đã mô tả khi không có lý do. Với hạn chế trả lời đơn giản, dùng `rm`: `a` mọi tin nhắn, `r` chỉ trả lời, `rb` trả lời bot, `rc` trả lời Combot, `nr` không phải trả lời. Không dùng `rm: "cr"` thay trường lệnh mới.

Không tạo trường cũ hoặc nội bộ `lf`, `fc`, `lo`, hay trường giao diện `actions`, `destination`, `topic`, `applyTarget` và `alwaysRun`. Định dạng Compact biểu diễn chúng khác, và một số cài đặt hoàn toàn không phải tính năng đang hoạt động.

Giới hạn khi lập kế hoạch:

- Free: tối đa 2 quy tắc đã lưu; Pro: tối đa 50; Business: tối đa 100. Quy tắc đang tắt cũng tính. Xét quy tắc hiện có khi tính chỗ còn lại.
- Phương án OR bổ sung mỗi quy tắc: Free 0, Pro 2, Business 5.
- Tối đa 100 dòng hành động mỗi quy tắc, với ngân sách hành động tính riêng là 20 cho mỗi lần thực thi kế hoạch.
- Một lượt gửi tốn 1 cho mỗi nơi nhận duy nhất, hoặc 2 khi dọn phản hồi trước. Hành động Telegram tác động người dùng được tính theo người nhận, nên `b` có thể dành gấp đôi. XP và danh tiếng tốn 0 trong phép tính này. Chế độ ngẫu nhiên tính các dòng bắt buộc cộng lựa chọn ngẫu nhiên đắt nhất.
- Đây là phép tính nội bộ, không phải lời hứa chính xác hai mươi yêu cầu mạng gồm mọi thao tác phụ. Nếu dòng tiếp theo vượt ngân sách còn lại, thực thi dừng; hành động hoàn tất không bị hoàn tác.

Không hứa chạy chỉ theo giờ mà không có sự kiện, “tối đa một lần mỗi giờ”, phần thưởng phản ứng một lần, chống lạm dụng thưởng do sự kiện lặp, chỉ lần đầu vượt ngưỡng, thực thi đúng một lần, xử lý nhóm ngoài tùy ý, tuổi tài khoản hoặc thống kê hoạt động trong khoảng quá khứ tùy ý. Nếu một điều trong số đó thiết yếu, giải thích rằng chỉ quy tắc được mô tả là chưa đủ.

Nhập thêm bản sao quy tắc mới; không chuyển đổi Triggers v2 cũ. Có thể viết lại ý nghĩa quy tắc cũ bằng Compact v3, nhưng không trình bày JSON cũ như bản sẵn sàng nhập.

## 15. Tình huống nghiệm thu cho ví dụ

Thư mục `examples` kèm theo chứa sáu gói độc lập, mỗi gói có một quy tắc đang tắt:

| Tệp | Trường hợp khớp | Kiểm tra bổ sung |
| --- | --- | --- |
| `01-course-command.json` | Thành viên nhập `/course_info` | Văn bản thường không có lệnh không được kích hoạt phản hồi |
| `02-recording-faq.json` | Văn bản chứa “bản ghi ở đâu” | Câu hỏi không liên quan không được kích hoạt phản hồi; tìm một phần có thể khớp cụm dài hơn |
| `03-random-welcome.json` | Thành viên mới vào nhóm | Chọn một lời chào, không phải cả ba |
| `04-moderator-reply-mute.json` | Quản trị viên Telegram hoặc chủ nhóm trả lời thành viên bằng `/team_pause` | Thành viên thường không được gọi; đối tượng quản trị viên bị loại trừ; lệnh không trả lời không được hạn chế người gửi |
| `05-known-link-join-request.json` | Yêu cầu dùng liên kết từ danh mục Combot | Nguồn ngoài hoặc chưa biết không được khớp; mọi liên kết đã biết đều khớp nếu chưa chọn liên kết cụ thể |
| `06-thumbs-up-reaction.json` | Người dùng thêm phản ứng và trạng thái mới chứa 👍 | Gỡ 👍 không khớp; thay đổi phù hợp lặp lại có thể gửi thêm tin nhắn |

Đây là tình huống nghiệm thu cho nhóm của bạn, không phải khẳng định tất cả đã được thực hiện. Kiểm tra đã hoàn tất nằm bên dưới. Mỗi ví dụ cần kiểm tra cài đặt và khả năng trong nhóm trước khi bật.

## 16. Nguồn định dạng và kiểm tra đã hoàn tất

Định dạng đã được đối chiếu với Rails `0d80ce4788ef5adc5c7c1b79e85c6b8be27cc00e` và bot `ddc1a8a6b6ab99bd2517d783870495990c7058e5`. Các phiên bản nhánh main này chứa bản sửa phối hợp cho trình chỉnh sửa và Automation. Việc hợp nhất Rails PR #78 và bot PR #56 đã được xác nhận trên Codeberg; chưa xác định độc lập phiên bản chính xác của tiến trình đã triển khai.

Nguồn chính: `trigger_compact_codec_helpers.js`, `trigger_import_export_helpers.js`, `trigger_validation_helpers.js`, danh mục sự kiện và hành động, `user_attribute_model_helpers.js`, `AutomationController`, hợp đồng Automation chi tiết trong `docs/MONGODB.md` và xử lý điều kiện/hành động trong `automation.py`.

Sáu ví dụ gốc đã được kiểm tra trong bộ nhớ bằng codec từ mã nguồn trình chỉnh sửa: giải mã, dựng lại, giải mã lần nữa và kiểm tra độ ổn định của kết quả chuẩn hóa. Hành động và trạng thái tắt được giữ. Codec bỏ một số giá trị mặc định, nên so sánh dùng kết quả chuẩn hóa thay vì yêu cầu từng byte giống JSON đầu vào.

Ngày 8 tháng 9, trạng thái tắt của cả sáu ví dụ gốc đã được kiểm tra sau khi nhập qua trình chỉnh sửa sản phẩm trên combot.org, lưu máy chủ và tải lại trang. Điều này không thay thế xác minh từng điều kiện và hành động trong Telegram.

Trường hợp lệnh và câu hỏi thường gặp đã được kiểm tra trong Telegram: yêu cầu phù hợp nhận phản hồi dự kiến, còn trường hợp đối chứng thì không. Chỉ `/course_info` được đổi thành tên thử nghiệm duy nhất được cơ chế bảo vệ của công cụ thử cho phép; các cài đặt ví dụ khác được giữ nguyên. Kết quả này không tự chứng minh sự kiện và hành động khác.

Với `06-thumbs-up-reaction.json`, thêm 👍 từ hồ sơ cá nhân tạo một phản hồi dự kiến; gỡ không tạo phản hồi. Danh tính và bộ phản ứng cũ/mới được xác nhận qua bộ quan sát Bot API riêng. Lời chào ngẫu nhiên khi vào nhóm, áp dụng tắt tiếng và chấp thuận yêu cầu tham gia thật chưa được thử trong lượt đó; nhập không chứng minh hành động thực thi.

Các quy tắc thử đã tạo được xóa và việc khôi phục danh sách gốc đã được kiểm tra; tin nhắn kết quả vẫn ở nhóm thử nghiệm. JSON Schema là tài liệu kèm theo, chưa kết nối với sản phẩm và không được trình bày như bộ kiểm tra tích hợp hiện có.

Ngày 9 tháng 9, tài liệu biên tập được đối chiếu với Rails `0d80ce4788ef5adc5c7c1b79e85c6b8be27cc00e` và bot `0a491a6ee50c57e98c1d9de04819253d15214506`. Các điểm làm rõ gồm giới hạn tên trong trình chỉnh sửa, nhóm quản trị viên, người tham gia sự kiện, người nhận hành động và liên kết danh sách tùy chọn. Đây là rà soát tài liệu dựa trên mã nguồn, không phải lượt thử Telegram mới. Nội dung ví dụ đã dịch chưa được thử trực tiếp độc lập.