Zalo

स्थिति: प्रयोगात्मक। डायरेक्ट मैसेज और समूह चैट, दोनों लागू हैं; नीचे दी गई क्षमताएँ तालिका Zalo Bot Creator / Marketplace बॉट पर सत्यापित व्यवहार दर्शाती है।

बंडल किया गया Plugin

वर्तमान OpenClaw रिलीज़ में Zalo बंडल किए गए Plugin के रूप में उपलब्ध है, इसलिए पैकेज किए गए बिल्ड के लिए अलग इंस्टॉलेशन की आवश्यकता नहीं होती।

किसी पुराने बिल्ड या Zalo को शामिल न करने वाले कस्टम इंस्टॉलेशन पर, npm पैकेज को सीधे इंस्टॉल करें:

• इंस्टॉल करें: openclaw plugins install @openclaw/zalo
• पिन किया गया संस्करण: openclaw plugins install @openclaw/zalo@2026.6.11
• स्थानीय चेकआउट से: openclaw plugins install ./path/to/local/zalo-plugin
• विवरण: Plugins

त्वरित सेटअप

1. https://bot.zaloplatforms.com पर बॉट टोकन बनाएँ (साइन इन करें, बॉट बनाएँ, सेटिंग्स कॉन्फ़िगर करें)। टोकन numeric_id:secret है; Marketplace बॉट के लिए उपयोग योग्य रनटाइम टोकन बॉट के स्वागत संदेश में दिखाई दे सकता है।
2. टोकन को या तो env 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 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"]) द्वारा समर्थित हैं और mention तथा समूह नीति से नियंत्रित होती हैं:

• 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 सेट करें।
  • Webhook URL में HTTPS का उपयोग होना चाहिए।
  • Webhook सीक्रेट 8-256 अक्षरों का होना चाहिए।
  • Zalo इवेंट को X-Bot-Api-Secret-Token हेडर के साथ भेजता है, जिसकी जाँच स्थिर-समय तुलना से की जाती है।
  • Gateway HTTP, Webhook अनुरोधों को channels.zalo.webhookPath पर संभालता है (डिफ़ॉल्ट रूप से Webhook URL का पथ)।
  • अनुरोधों को 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 को इवेंट प्राप्त नहीं हो रहे:

• पुष्टि करें कि Webhook URL HTTPS का उपयोग करता है
• पुष्टि करें कि सीक्रेट 8-256 अक्षरों का है
• पुष्टि करें कि Gateway HTTP एंडपॉइंट कॉन्फ़िगर किए गए पथ पर पहुँच योग्य है
• पुष्टि करें कि getUpdates पोलिंग भी नहीं चल रही है (वे परस्पर अनन्य हैं)
• अनुरोधों के अचानक बढ़ने पर HTTP 429 लौट सकता है (प्रति पथ+IP 120 अनुरोध / 60s); कुछ समय प्रतीक्षा करके पुनः प्रयास करें

कॉन्फ़िगरेशन संदर्भ

पूर्ण कॉन्फ़िगरेशन: कॉन्फ़िगरेशन

channels.zalo.botToken, channels.zalo.dmPolicy, और अन्य फ़्लैट शीर्ष-स्तरीय कुंजियाँ ऊपर दिए गए फ़ील्ड के लिए पुराने एकल-अकाउंट संक्षिप्त रूप हैं; दोनों रूप समर्थित हैं।

Env विकल्प: ZALO_BOT_TOKEN=... केवल डिफ़ॉल्ट अकाउंट के टोकन को रिज़ॉल्व करता है।

संबंधित

• चैनल अवलोकन - सभी समर्थित चैनल
• पेयरिंग - डायरेक्ट मैसेज प्रमाणीकरण और पेयरिंग प्रवाह
• समूह - समूह चैट व्यवहार और mention नियंत्रण
• चैनल रूटिंग - संदेशों के लिए सत्र रूटिंग
• सुरक्षा - एक्सेस मॉडल और सुदृढ़ीकरण