Zalo

สถานะ: อยู่ระหว่างการทดลอง รองรับทั้งข้อความส่วนตัวและแชตกลุ่มแล้ว ตารางความสามารถด้านล่างแสดงพฤติกรรมที่ผ่านการตรวจสอบแล้วบนบอต Zalo Bot Creator / Marketplace

Plugin ที่มาพร้อมระบบ

Zalo จัดส่งเป็น Plugin ที่มาพร้อมกับ OpenClaw รุ่นปัจจุบัน ดังนั้นบิลด์แบบแพ็กเกจจึงไม่จำเป็นต้องติดตั้งแยกต่างหาก

สำหรับบิลด์รุ่นเก่าหรือการติดตั้งแบบกำหนดเองที่ไม่รวม Zalo ให้ติดตั้งแพ็กเกจ npm โดยตรง:

• ติดตั้ง: openclaw plugins install @openclaw/zalo
• รุ่นที่ตรึงไว้: openclaw plugins install @openclaw/zalo@2026.6.11
• จากเช็กเอาต์ในเครื่อง: openclaw plugins install ./path/to/local/zalo-plugin
• รายละเอียด: Plugin

การตั้งค่าอย่างรวดเร็ว

1. สร้างโทเค็นบอตที่ https://bot.zaloplatforms.com (ลงชื่อเข้าใช้ สร้างบอต และกำหนดการตั้งค่า) โทเค็นมีรูปแบบ numeric_id:secret สำหรับบอต Marketplace โทเค็นรันไทม์ที่ใช้งานได้อาจปรากฏในข้อความต้อนรับของบอต
2. ตั้งค่าโทเค็นผ่านตัวแปรสภาพแวดล้อม ZALO_BOT_TOKEN=... (เฉพาะบัญชีเริ่มต้น) หรือในไฟล์กำหนดค่า
3. รีสตาร์ต Gateway
4. อนุมัติรหัสการจับคู่เมื่อได้รับข้อความส่วนตัวครั้งแรก (นโยบายข้อความส่วนตัวเริ่มต้นคือการจับคู่)

การกำหนดค่าขั้นต่ำ:

{  channels: {    zalo: {      enabled: true,      accounts: {        default: {          botToken: "12345689:abc-xyz",          dmPolicy: "pairing",        },      },    },  },}

หลายบัญชี: เพิ่มรายการภายใต้ channels.zalo.accounts.<id> โดยแต่ละรายการมี botToken/name ของตนเอง channels.zalo.botToken (รูปแบบแบนโดยไม่มี accounts) เป็นรูปแบบย่อแบบเดิมสำหรับบัญชีเดียว สำหรับการกำหนดค่าใหม่ควรใช้ accounts.<id>.*

คืออะไร

Zalo เป็นแอปส่งข้อความที่เน้นผู้ใช้ในเวียดนาม Bot API ของ Zalo ช่วยให้ Gateway เรียกใช้บอตได้ทั้งสำหรับการสนทนาแบบตัวต่อตัวและแชตกลุ่ม พร้อมกำหนดเส้นทางกลับไปยัง Zalo อย่างแน่นอน (โมเดลจะไม่เลือกช่องทางเอง)

หน้านี้ครอบคลุม บอต Zalo Bot Creator / Marketplace ส่วน บอต Zalo Official Account (OA) เป็นพื้นผิวผลิตภัณฑ์อีกแบบหนึ่งและอาจมีพฤติกรรมแตกต่างกัน หน้านี้ไม่ครอบคลุมบอตประเภทดังกล่าว

วิธีการทำงาน

• ข้อความขาเข้าจะถูกปรับให้อยู่ในรูปแบบเอนเวโลปช่องทางที่ใช้ร่วมกัน พร้อมตัวยึดตำแหน่งสื่อ
• การตอบกลับจะถูกส่งกลับไปยังแชต Zalo เดิมเสมอ โดยไม่ใช้การตอบกลับแบบอ้างข้อความ (replyToMode ถูกปิดไว้อย่างถาวร)
• ค่าเริ่มต้นใช้การสำรวจแบบยาว (getUpdates) และสามารถใช้โหมด Webhook ผ่าน channels.zalo.webhookUrl
• ในกลุ่มต้อง @กล่าวถึงบอตจึงจะเรียกใช้งานได้ และไม่สามารถกำหนดค่านี้แยกตามช่องทาง

ขีดจำกัด

การควบคุมการเข้าถึง

ข้อความส่วนตัว

• channels.zalo.dmPolicy: pairing (ค่าเริ่มต้น) | allowlist | open | disabled
• การจับคู่: ผู้ส่งที่ไม่รู้จักจะได้รับรหัสการจับคู่ โดยข้อความจะถูกละเว้นจนกว่าจะได้รับอนุมัติ รหัสจะหมดอายุหลังจาก 1 ชั่วโมง
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • รายละเอียด: การจับคู่
• channels.zalo.allowFrom รับรหัสผู้ใช้ Zalo แบบตัวเลข (ไม่รองรับการค้นหาด้วยชื่อผู้ใช้) ค่า open ต้องกำหนด "*"

กลุ่ม

Plugin รองรับแชตกลุ่ม (chatTypes: ["direct", "group"]) และควบคุมด้วยการกล่าวถึงร่วมกับนโยบายกลุ่ม:

• channels.zalo.groupPolicy: open | allowlist | disabled
• channels.zalo.groupAllowFrom จำกัดรหัสผู้ส่งที่สามารถเรียกใช้บอตในกลุ่ม หากไม่ได้ตั้งค่าจะใช้ allowFrom
• การหาค่าเริ่มต้น: เมื่อกำหนดค่า channels.zalo แล้ว groupPolicy ที่ไม่ได้ตั้งค่าจะมีค่าเป็น open แต่หากไม่มี channels.zalo เลย รันไทม์จะปิดกั้นโดยใช้ allowlist
• ข้อควรระวังจากการใช้งานจริง: ในการตั้งค่าบอต Marketplace บางแบบ ไม่สามารถเพิ่มบอตลงในกลุ่มได้เลย หากพบปัญหานี้ ให้ตรวจสอบการตั้งค่า Zalo Bot Platform ของบอต ซึ่งเป็นข้อจำกัดจากฝั่งแพลตฟอร์ม ไม่ใช่นโยบายของ OpenClaw

การสำรวจแบบยาวเทียบกับ Webhook

• ค่าเริ่มต้น: การสำรวจแบบยาว (ไม่ต้องใช้ URL สาธารณะ)
• โหมด Webhook: ตั้งค่า channels.zalo.webhookUrl และ channels.zalo.webhookSecret
  • URL ของ Webhook ต้องใช้ HTTPS
  • ข้อมูลลับของ Webhook ต้องมีความยาว 8-256 อักขระ
  • Zalo ส่งเหตุการณ์พร้อมส่วนหัว X-Bot-Api-Secret-Token ซึ่งตรวจสอบด้วยการเปรียบเทียบแบบใช้เวลาคงที่
  • HTTP ของ Gateway จัดการคำขอ Webhook ที่ channels.zalo.webhookPath (ค่าเริ่มต้นคือพาธของ URL Webhook)
  • คำขอต้องใช้ Content-Type: application/json (หรือชนิดสื่อ +json)
  • ตามเอกสาร Zalo API การสำรวจด้วย getUpdates และ Webhook ไม่สามารถใช้งานพร้อมกันได้

ประเภทข้อความที่รองรับ

• ข้อความ: รองรับเต็มรูปแบบ โดยแบ่งเป็นส่วนละ 2,000 อักขระ
• สื่อ: รองรับทั้งขาเข้าและขาออก โดยจำกัดด้วย mediaMaxMb
• รีแอ็กชัน เธรด แบบสำรวจ และคำสั่งแบบเนทีฟ: Plugin ไม่รองรับ
• การสตรีม: Plugin ประกาศความสามารถการสตรีมแบบบล็อก แต่ Zalo ไม่มีตัวเลือกเฉพาะสำหรับปรับแต่งคิวขาออกหรือการรวมข้อความ (ต่างจากช่องทางระดับภูมิภาคบางช่องทาง) หากสิ่งนี้สำคัญต่อกรณีใช้งานของคุณ ให้ตรวจสอบพฤติกรรมปัจจุบันในสภาพแวดล้อมของคุณ

ความสามารถ

เป้าหมายการส่ง (CLI/Cron)

ใช้รหัสแชตเป็นเป้าหมาย:

openclaw message send --channel zalo --target 123456789 --message "hi"

การแก้ไขปัญหา

บอตไม่ตอบสนอง:

• ตรวจสอบโทเค็น: openclaw channels status --probe
• ตรวจสอบว่าผู้ส่งได้รับอนุมัติแล้ว (ผ่านการจับคู่หรือ allowFrom)
• ตรวจสอบบันทึกของ Gateway: openclaw logs --follow

Webhook ไม่ได้รับเหตุการณ์:

• ยืนยันว่า URL ของ Webhook ใช้ HTTPS
• ยืนยันว่าข้อมูลลับมีความยาว 8-256 อักขระ
• ยืนยันว่าเข้าถึงเอนด์พอยต์ HTTP ของ Gateway ได้ผ่านพาธที่กำหนดค่า
• ยืนยันว่าไม่ได้ใช้งานการสำรวจด้วย getUpdates พร้อมกัน (ทั้งสองอย่างไม่สามารถใช้งานพร้อมกันได้)
• คำขอจำนวนมากในช่วงสั้น ๆ อาจได้รับ HTTP 429 (120 คำขอ / 60 วินาทีต่อพาธ+IP) ให้เว้นระยะแล้วลองอีกครั้ง

ข้อมูลอ้างอิงการกำหนดค่า

การกำหนดค่าฉบับเต็ม: การกำหนดค่า

channels.zalo.botToken, channels.zalo.dmPolicy และคีย์ระดับบนสุดแบบแบนอื่น ๆ เป็นรูปแบบย่อแบบเดิมสำหรับบัญชีเดียวของฟิลด์ด้านบน โดยรองรับทั้งสองรูปแบบ

ตัวเลือกตัวแปรสภาพแวดล้อม: ZALO_BOT_TOKEN=... ใช้กำหนดโทเค็นของบัญชีเริ่มต้นเท่านั้น

เนื้อหาที่เกี่ยวข้อง

• ภาพรวมช่องทาง - ช่องทางที่รองรับทั้งหมด
• การจับคู่ - การยืนยันตัวตนผ่านข้อความส่วนตัวและขั้นตอนการจับคู่
• กลุ่ม - พฤติกรรมของแชตกลุ่มและการควบคุมด้วยการกล่าวถึง
• การกำหนดเส้นทางช่องทาง - การกำหนดเส้นทางเซสชันสำหรับข้อความ
• ความปลอดภัย - รูปแบบการเข้าถึงและการเสริมความปลอดภัย