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. ตั้งค่าโทเค็นโดยใช้ env ZALO_BOT_TOKEN=... (สำหรับบัญชีเริ่มต้นเท่านั้น) หรือในไฟล์กำหนดค่า
3. รีสตาร์ต Gateway
4. อนุมัติรหัสการจับคู่เมื่อมีการติดต่อผ่าน DM ครั้งแรก (นโยบาย DM เริ่มต้นคือการจับคู่)

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

{  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 ของแอปช่วยให้ Gateway เรียกใช้บอตได้ทั้งสำหรับการสนทนาแบบ 1:1 และแชตกลุ่ม พร้อมกำหนดเส้นทางกลับไปยัง Zalo อย่างแน่นอน (โมเดลจะไม่เลือกช่องทางเอง)

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

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

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

ขีดจำกัด

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

ข้อความโดยตรง

• 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)
  • ระบบจะส่งคืน HTTP 200 หลังจากจัดเก็บเหตุการณ์ดิบอย่างถาวรแล้วเท่านั้น หากจัดเก็บไม่สำเร็จจะส่งคืน HTTP 500
  • ตามเอกสาร Zalo API การโพล getUpdates และ Webhook ไม่สามารถใช้งานพร้อมกันได้

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

• ข้อความ: รองรับเต็มรูปแบบ โดยแบ่งเป็นส่วนละ 2000 อักขระ
• สื่อ: รองรับทั้งขาเข้าและขาออก โดยจำกัดตาม 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 คำขอ / 60s ต่อพาธ+IP) ให้ชะลอและลองใหม่

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

การกำหนดค่าทั้งหมด: การกำหนดค่า

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

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

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

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