ZaloSendMessage Node - Gửi tin nhắn đa năng trong n8n

Tổng quan

ZaloSendMessage là node cốt lõi để gửi tin nhắn Zalo với đầy đủ tính năng như tin nhắn text, ảnh, file, video, markdown formatting, mention người dùng, quote reply và nhiều hơn nữa.

Use Cases chính

• 📤 Gửi tin nhắn marketing hàng loạt
• 🤖 Auto-reply khách hàng
• 📢 Thông báo hệ thống
• 📊 Báo cáo tự động
• 🎉 Chúc mừng sinh nhật/sự kiện
• 🎬 Gửi video sản phẩm/hướng dẫn

---

Features

ZaloSendMessage hỗ trợ nhiều tính năng mạnh mẽ:

1. Markdown Formatting

**Bold text**
_Italic text_
[red]Red color text[/red]
[blue]Blue color text[/blue]

2. Gửi Ảnh

• Single image (URL)
• Multiple images (array of URLs)
• Auto HEIC/HEIF → JPEG conversion
• Support local files & remote URLs

3. Gửi Video 🆕

• URL Mode: Gửi video từ URL công khai
• Binary Mode: Gửi video từ file (upload từ HTTP Request, Read File...)
• Tự động tạo thumbnail từ video (cần ffmpeg)
• Tự động lấy metadata (duration, width, height) từ video (cần ffprobe)
• Hỗ trợ định dạng MP4
• Upload tự động lên hosting tạm nếu dùng binary

4. Gửi Files

• Documents (PDF, DOCX, XLSX, etc.)
• Audio
• Max size: 50MB/file

5. Quote Reply

Trích dẫn tin nhắn trước đó:

{
  "quoteMessageId": "message_id_here"
}

6. @Mention Users 🆕 Enhanced

Tag người dùng trong tin nhắn với syntax mới trực tiếp trong message:

Syntax hỗ trợ:

Syntax	Mô tả	Ví dụ
@[uid]	Mention user theo ID	@[2234791809511721207] Hello!
@all	Mention tất cả (group only)	@all Xin chú ý!

Ví dụ sử dụng:

{
  "message": "@[2234791809511721207] please review và @all check this!"
}

Kết quả hiển thị: @user please review và @all check this!

7. Priority Levels

• Mặc định: Normal message
• Quan trọng: Important (yellow)
• Khẩn cấp: Urgent (red)

8. TTL (Time To Live)

Tự xóa tin nhắn sau X giây:

{
  "ttl": 300 // Xóa sau 5 phút
}

---

Parameters

Required Parameters

Parameter	Type	Mô tả
Credential	Credential	Zalo credential (từ ZaloLoginByQr)
To	String	User ID hoặc Group ID nhận tin
Message	String	Nội dung tin nhắn

Optional Parameters

Parameter	Type	Default	Mô tả
Message Type	Dropdown	Text	text / image / file / video / sticker
Images	String/Array	-	URL ảnh (single hoặc array)
Files	String/Array	-	URL file đính kèm
Quote Message ID	String	-	ID tin nhắn để quote reply
Mentions	Array	[]	Danh sách user IDs để mention
Priority	Dropdown	Normal	Normal / Important / Urgent
TTL	Number	-	Thời gian tự xóa (giây)
Width	Number	Auto	Chiều rộng ảnh (px)
Height	Number	Auto	Chiều cao ảnh (px)

Video Parameters (khi Message Type = video) 🆕

Parameter	Type	Default	Mô tả
Video Source	Dropdown	url	url (từ URL) hoặc binary (từ file)
Video URL	String	-	URL video công khai (cho URL mode)
Video Binary Property	String	data	Tên property chứa binary (cho Binary mode)
Thumbnail URL	String	-	URL thumbnail (auto nếu có ffmpeg)
Video Message	String	-	Tin nhắn đi kèm video
Auto Video Metadata	Boolean	true	Tự động lấy duration/width/height
Video Duration	Number	Auto	Thời lượng video (ms)
Video Width	Number	Auto	Chiều rộng video (px)
Video Height	Number	Auto	Chiều cao video (px)

---

Examples

Example 1: Gửi tin nhắn text đơn giản

Scenario: Gửi tin nhắn chào khách hàng

{
  "nodes": [
    {
      "name": "Send Welcome",
      "type": "n8n-nodes-zalo-nnt.zaloSendMessage",
      "parameters": {
        "toId": "{{$json.userId}}",
        "message": "Chào mừng bạn đến với dịch vụ của chúng tôi! 👋"
      },
      "credentials": {
        "zaloApi": "Zalo Main Account"
      }
    }
  ]
}

Result: Khách hàng nhận tin nhắn chào mừng ngay sau khi đăng ký.

---

Example 2: Gửi tin với Markdown formatting

Scenario: Gửi thông báo quan trọng với format đẹp

{
  "parameters": {
    "toId": "user123",
    "message": "**THÔNG BÁO QUAN TRỌNG**\n\nĐơn hàng #12345 của bạn đã được *xác nhận*.\n\n[blue]Thời gian giao hàng dự kiến:[/blue] 2-3 ngày\n[red]Tổng tiền:[/red] 500,000 VNĐ",
    "priority": "Important"
  }
}

Result: Tin nhắn được highlight với màu sắc và độ ưu tiên cao.

---

Example 3: Gửi nhiều ảnh

Scenario: Gửi album sản phẩm mới

{
  "parameters": {
    "toId": "group789",
    "message": "🎉 Ra mắt bộ sưu tập mùa hè 2024!",
    "messageType": "image",
    "images": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg",
      "https://example.com/image3.jpg"
    ]
  }
}

Result: Tin nhắn kèm 3 ảnh sản phẩm.

---

Example 4: Quote Reply với Mention 🆕

Scenario: Trả lời câu hỏi khách hàng với mention syntax mới

{
  "parameters": {
    "toId": "group123",
    "message": "@[{{$json.userId}}] Cảm ơn bạn đã hỏi! Sản phẩm này còn hàng nhé 😊",
    "quoteMessageId": "{{$json.originalMessageId}}"
  }
}

Result: Tin nhắn trích dẫn câu hỏi gốc và tag khách hàng. Hiển thị: @user Cảm ơn bạn đã hỏi!...

Ví dụ với @all:

{
  "parameters": {
    "toId": "group123",
    "message": "@all Thông báo quan trọng: Meeting lúc 3PM hôm nay!"
  }
}

Result: Tất cả thành viên trong group được mention.

---

Example 5: Gửi file với TTL

Scenario: Gửi file báo cáo tự xóa sau 1 giờ

{
  "parameters": {
    "toId": "group_managers",
    "message": "📊 Báo cáo bán hàng hôm nay (tự xóa sau 1h)",
    "messageType": "file",
    "files": "https://example.com/daily-report.pdf",
    "ttl": 3600
  }
}

Result: File được gửi và tự động xóa sau 3600 giây (1 giờ).

---

Example 6: Gửi video từ URL 🆕

Scenario: Gửi video hướng dẫn sản phẩm từ URL

{
  "parameters": {
    "toId": "user123",
    "messageType": "video",
    "videoSource": "url",
    "videoUrl": "https://example.com/product-guide.mp4",
    "thumbnailUrl": "https://example.com/thumbnail.jpg",
    "videoMessage": "🎬 Video hướng dẫn sử dụng sản phẩm mới!",
    "autoVideoMetadata": true
  }
}

Result: Video được gửi với thumbnail và message đi kèm. Duration/width/height được tự động detect.

---

Example 7: Gửi video từ Binary (HTTP Request → Zalo) 🆕

Scenario: Download video từ API rồi gửi qua Zalo

Workflow structure:

HTTP Request (download video) → ZaloSendMessage (binary mode)

HTTP Request node (download video):

{
  "parameters": {
    "url": "https://api.example.com/videos/123.mp4",
    "responseFormat": "file"
  }
}

ZaloSendMessage node:

{
  "parameters": {
    "toId": "group789",
    "messageType": "video",
    "videoSource": "binary",
    "videoBinaryProperty": "data",
    "videoMessage": "📹 Video mới từ hệ thống!",
    "autoVideoMetadata": true
  }
}

Result:

1. Video được upload tự động lên hosting tạm (catbox.moe)
2. Thumbnail được tự động tạo và upload (nếu có ffmpeg)
3. Video được gửi đến Zalo group

---

Example 8: Gửi video với metadata thủ công 🆕

Scenario: Gửi video khi server không có ffmpeg/ffprobe

{
  "parameters": {
    "toId": "user456",
    "messageType": "video",
    "videoSource": "url",
    "videoUrl": "https://cdn.example.com/video.mp4",
    "thumbnailUrl": "https://cdn.example.com/video-thumb.jpg",
    "videoMessage": "Video sản phẩm",
    "autoVideoMetadata": false,
    "videoDuration": 45000,
    "videoWidth": 1920,
    "videoHeight": 1080
  }
}

Result: Video được gửi với metadata được chỉ định thủ công (duration: 45 giây, 1920x1080).

---

Common Use Cases

1. Marketing Campaign

Gửi tin nhắn hàng loạt với personalization:

// Workflow logic
// 1. Load customers từ Google Sheets
// 2. Template message với personalization
// 3. Send to each customer với delay

const message = `Chào ${customerName}, đặc biệt cho ${company}: Giảm 20% hôm nay!`;

2. Customer Support Auto-reply

Workflow tự động trả lời:

Trigger: ZaloMessageTrigger
Condition: message contains 'giá' or 'price'
Action: ZaloSendMessage with price list

3. System Monitoring

Gửi alert khi có lỗi:

{
  "parameters": {
    "toId": "group_tech_team",
    "message": "🚨 **CẢNH BÁO HỆ THỐNG**\n\nLỗi: {{$json.error}}\nTime: {{$now}}",
    "priority": "Urgent"
  }
}

---

Advanced Configuration

HEIC/HEIF Auto-conversion

Node tự động convert ảnh HEIC/HEIF (từ iPhone) sang JPEG:

{
  "images": "https://example.com/photo.heic"
  // Tự động convert → JPEG
}

Batch Sending với Rate Limiting

Gửi hàng loạt an toàn:

// Function node
const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

for (let i = 0; i < items.length; i++) {
  // Gửi tin nhắn
  await sendMessage(items[i]);

  // Delay 2 giây giữa các tin
  await delay(2000);
}

Dynamic Mentions 🆕

Mention nhiều người từ data với syntax mới:

// Function node - Build message with mentions
const participants = $json.participants; // [{userId: "123"}, {userId: "456"}]

// Build mention string directly in message
const mentionTags = participants.map((p) => `@[${p.userId}]`).join(" ");

return {
  message: `Chào mừng ${mentionTags} - ${participants.length} thành viên mới!`,
};
// Result: "Chào mừng @[123] @[456] - 2 thành viên mới!"
// Display: "Chào mừng @user @user - 2 thành viên mới!"

Mention all + specific users:

return {
  message: `@all Thông báo: @[${$json.adminId}] vừa thêm tính năng mới!`,
};

---

Troubleshooting

❌ Lỗi: "Failed to send message"

Nguyên nhân:

• Credential expired
• User ID không đúng
• Network issues

Giải pháp:

1. Kiểm tra credential: Re-authenticate nếu cần
2. Verify User ID (check với ZaloUser node)
3. Check n8n logs

❌ Ảnh không gửi được

Nguyên nhân:

• URL không public
• File size quá lớn (>10MB)
• Format không hỗ trợ

Giải pháp:

• Đảm bảo URL public accessible
• Resize ảnh < 10MB
• Sử dụng format: JPG, PNG, GIF, HEIC

❌ Markdown không render

Nguyên nhân: Syntax sai

Đúng:

**bold** *italic* [red]text[/red]

Sai:

<b>bold</b> <red>text</red>

❌ Mention không hoạt động 🆕

Nguyên nhân:

• Sử dụng mention trong chat 1-1 (chỉ hoạt động trong GROUP)
• User ID không hợp lệ
• Syntax mention sai

Giải pháp:

1. Đảm bảo gửi mention trong GROUP chat, không phải chat 1-1
2. Sử dụng đúng syntax:
   • @[uid] → Mention user cụ thể
   • @all → Mention tất cả
3. Lấy đúng User ID từ ZaloUser node hoặc ZaloMessageTrigger
4. Kiểm tra user có trong group không

Ví dụ syntax đúng:

@[2234791809511721207] Hello!   ✅
@all Check this!                ✅
@username Hello!                ❌ (không hỗ trợ mention by name)

❌ Video lỗi "Tham số không hợp lệ" 🆕

Nguyên nhân:

• Thumbnail URL không hợp lệ hoặc không accessible
• Video URL không public
• Thiếu thumbnail (và không có ffmpeg để tự tạo)

Giải pháp:

1. Kiểm tra thumbnail URL có accessible không (mở thử trên browser)
2. Đảm bảo video URL public (không cần auth)
3. Nếu dùng Binary mode: cài ffmpeg hoặc cung cấp thumbnailUrl thủ công

❌ Video Binary mode không tạo được thumbnail 🆕

Nguyên nhân: Server n8n không có ffmpeg/ffprobe

Giải pháp (Docker):

# Thêm vào Dockerfile
FROM n8nio/n8n:latest
USER root
RUN apk add --no-cache ffmpeg
USER node

Hoặc rebuild container với ffmpeg:

docker-compose down
docker-compose build --no-cache
docker-compose up -d

Giải pháp (workaround): Cung cấp thumbnailUrl thủ công thay vì dựa vào auto-generate.

❌ Video upload failed (Binary mode) 🆕

Nguyên nhân:

• Catbox.moe hosting tạm thời unavailable
• Video quá lớn (>200MB)
• Network timeout

Giải pháp:

1. Thử lại sau vài phút
2. Giảm kích thước video
3. Sử dụng URL mode với video đã upload lên CDN

❌ Video metadata không đúng 🆕

Nguyên nhân: ffprobe không detect được hoặc không có

Giải pháp:

• Tắt autoVideoMetadata và nhập thủ công videoDuration, videoWidth, videoHeight
• Cài ffprobe (đi kèm ffmpeg)

---

Rate Limiting

Zalo có giới hạn số tin nhắn/phút để tránh spam:

Loại	Giới hạn	Khuyến nghị
Tin cá nhân	~30/phút	Delay 2s/tin
Tin nhóm	~60/phút	Delay 1s/tin
Ảnh/File	~20/phút	Delay 3s/tin

Best practice: Sử dụng delay 2-3 giây giữa các tin nhắn.

---

Tips & Best Practices

---

Bước tiếp theo

Trong bài tiếp theo, chúng ta sẽ tìm hiểu về ZaloGroup Node - node quản lý nhóm Zalo toàn diện với 17 operations.