Gửi tin nhắn nhóm Zalo với Mention

Hướng dẫn triển khai tham số mentions trong payload gửi tin nhắn vào nhóm Zalo cá nhân.

📌 1. Tổng quan

API hỗ trợ gửi tin nhắn vào nhóm Zalo cho phép bạn mention một hoặc nhiều thành viên trong nội dung tin nhắn. Điều này được thực hiện bằng cách bổ sung trường mentions vào body request theo đúng vị trí ký tự trong chuỗi message.

---

📦 2. Cấu trúc payload

Schema tổng quát với mentions

{
  "message": "string",
  "group_id": "string",
  "mentions": [
    {
      "pos": 0,
      "len": 0,
      "uid": "string",
      "type": 0
    }
  ]
}

---

🧠 3. Nguyên tắc hoạt động của mention

3.1. pos – vị trí bắt đầu

• Là vị trí tính theo index ký tự trong chuỗi message

• Bắt đầu từ 0

3.2. len – độ dài đoạn text được mention

• Chính là số ký tự tạo thành tag trong nội dung Ví dụ: @Nam → độ dài = 4

3.3. uid – người được mention

• UID của người dùng trong nhóm Zalo

• Nếu muốn mention all, dùng uid: "-1"

3.4. type

• 0 → mention người dùng

• 1 → (tùy nền tảng, thường dùng cho dạng mention nâng cao — bạn giữ giá trị theo schema)

---

📝 4. Ví dụ minh họa

4.1. Mention 1 người

Giả sử bạn muốn gửi nội dung sau:

Chào @Nam, bạn kiểm tra giúp mình nhé.

Chuỗi message thực tế:

• "Chào @Nam, bạn kiểm tra giúp mình nhé."

Tính toán vị trí:

• "Chào " → 5 ký tự

• "@Nam" → độ dài 4 → pos = 5 → len = 4

Payload:

{
  "message": "Chào @Nam, bạn kiểm tra giúp mình nhé.",
  "group_id": "123456789",
  "mentions": [
    {
      "pos": 5,
      "len": 4,
      "uid": "UID_CUA_NAM",
      "type": 0
    }
  ]
}

---

4.2. Mention nhiều người

Message:

@Nam và @Lan ơi, họp lúc 3h nhé.

Tính vị trí:

• @Nam bắt đầu tại pos = 0, len = 4

• @Lan bắt đầu tại pos = 9 (vì "@Nam và " = 9 ký tự), len = 4

Payload:

{
  "message": "@Nam và @Lan ơi, họp lúc 3h nhé.",
  "group_id": "123456789",
  "mentions": [
    {
      "pos": 0,
      "len": 4,
      "uid": "UID_NAM",
      "type": 0
    },
    {
      "pos": 9,
      "len": 4,
      "uid": "UID_LAN",
      "type": 0
    }
  ]
}

---

4.3. Mention All

Message:

@all mọi người chú ý!

• "@all" → 4 ký tự

• pos = 0

• uid = "-1"

Payload:

{
  "message": "@all mọi người chú ý!",
  "group_id": "123456789",
  "mentions": [
    {
      "pos": 0,
      "len": 4,
      "uid": "-1",
      "type": 0
    }
  ]
}

Tuy nhiên:

Với Mention All, hệ thống sẽ tự động xác định tham số mentions mà bạn không cần phải truyền khi gọi API.

Bạn chỉ cần đảm bảo trong message có từ khóa @all. Hệ thống sẽ tự động render toàn bộ thành viên trong nhóm.

Ví dụ minimal:

{
  "message": "@all mọi người chú ý!",
  "group_id": "123456789"
}

---

✔️ 5. Lưu ý quan trọng

• Chuỗi message bắt buộc phải chứa chính xác đoạn text mention (ví dụ: @Nam)

• pos và len phải khớp tuyệt đối với vị trí ký tự trong message

• Nếu sai chỉ 1 ký tự, Zalo sẽ không render mention

• Mention all chỉ cần uid = "-1" và type = 0