Zalo (Bot API)¶

اسٹیٹس: تجرباتی۔ صرف ڈائریکٹ میسیجز؛ گروپس جلد آئیں گے، Zalo ڈاکس کے مطابق۔

پلگ اِن درکار ہے¶

Zalo ایک پلگ اِن کے طور پر فراہم کیا جاتا ہے اور کور انسٹال میں شامل نہیں۔

• CLI کے ذریعے انسٹال کریں: openclaw plugins install @openclaw/zalo
• یا آن بورڈنگ کے دوران Zalo منتخب کریں اور انسٹال پرامپٹ کی تصدیق کریں
• تفصیلات: Plugins

فوری سیٹ اپ (مبتدی)¶

1. Zalo پلگ اِن انسٹال کریں: - سورس چیک آؤٹ سے: openclaw plugins install ./extensions/zalo - npm سے (اگر شائع ہو): openclaw plugins install @openclaw/zalo - یا آن بورڈنگ میں Zalo منتخب کریں اور انسٹال پرامپٹ کی تصدیق کریں
2. ٹوکن سیٹ کریں: - Env: ZALO_BOT_TOKEN=... - یا کنفیگ: channels.zalo.botToken: "..."۔
3. گیٹ وے ری اسٹارٹ کریں (یا آن بورڈنگ مکمل کریں)۔
4. DM رسائی بطورِ طے شدہ pairing ہے؛ پہلی بار رابطے پر pairing کوڈ کی منظوری دیں۔

کم از کم کنفیگ:

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

یہ کیا ہے¶

Zalo ویتنام پر مرکوز میسیجنگ ایپ ہے؛ اس کا Bot API گیٹ وے کو 1:1 گفتگو کے لیے بوٹ چلانے دیتا ہے۔ یہ سپورٹ یا نوٹیفکیشنز کے لیے موزوں ہے جہاں آپ Zalo کی طرف متعین روٹنگ چاہتے ہیں۔

• گیٹ وے کی ملکیت والا Zalo Bot API چینل۔
• متعین روٹنگ: جوابات Zalo ہی کو واپس جاتے ہیں؛ ماڈل چینلز کا انتخاب نہیں کرتا۔
• DMs ایجنٹ کے مرکزی سیشن کو شیئر کرتے ہیں۔
• گروپس فی الحال معاون نہیں (Zalo دستاویزات میں "coming soon" درج ہے)۔

سیٹ اپ (تیز راستہ)¶

1. بوٹ ٹوکن بنائیں (Zalo Bot Platform)¶

1. https://bot.zaloplatforms.com پر جائیں اور سائن اِن کریں۔
2. نیا بوٹ بنائیں اور اس کی سیٹنگز کنفیگر کریں۔
3. بوٹ ٹوکن کاپی کریں (فارمیٹ: 12345689:abc-xyz)۔

2) ٹوکن کنفیگر کریں (env یا کنفیگ)¶

مثال:

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

Env آپشن: ZALO_BOT_TOKEN=... (صرف ڈیفالٹ اکاؤنٹ کے لیے کام کرتا ہے)۔

ملٹی اکاؤنٹ سپورٹ: ہر اکاؤنٹ کے ٹوکنز کے ساتھ channels.zalo.accounts استعمال کریں اور اختیاری name شامل کریں۔

3. gateway کو ری اسٹارٹ کریں۔ Zalo اس وقت شروع ہوتا ہے جب ٹوکن ریزولو ہو جائے (env یا config)۔
4. DM رسائی ڈیفالٹ طور پر pairing پر ہوتی ہے۔ جب بوٹ سے پہلی بار رابطہ کیا جائے تو کوڈ منظور کریں۔

یہ کیسے کام کرتا ہے (رویہ)¶

• آنے والے پیغامات کو میڈیا پلیس ہولڈرز کے ساتھ مشترکہ چینل اینویلپ میں نارملائز کیا جاتا ہے۔
• جوابات ہمیشہ اسی Zalo چیٹ پر واپس جاتے ہیں۔
• بطورِ طے شدہ لانگ پولنگ؛ ویب ہُک موڈ channels.zalo.webhookUrl کے ساتھ دستیاب ہے۔

حدود¶

• آؤٹ باؤنڈ متن 2000 حروف میں تقسیم کیا جاتا ہے (Zalo API حد)۔
• میڈیا ڈاؤن لوڈز/اپ لوڈز channels.zalo.mediaMaxMb تک محدود ہیں (ڈیفالٹ 5)۔
• 2000 حروف کی حد کی وجہ سے اسٹریمنگ کم مفید ہونے پر بطورِ طے شدہ بلاک ہے۔

رسائی کا کنٹرول (DMs)¶

DM رسائی¶

• ڈیفالٹ: channels.zalo.dmPolicy = "pairing"۔ نامعلوم ارسال کنندگان کو ایک پیئرنگ کوڈ ملتا ہے؛ منظوری تک پیغامات نظرانداز کیے جاتے ہیں (کوڈز 1 گھنٹے بعد ختم ہو جاتے ہیں)۔
• منظوری دیں بذریعہ:
• openclaw pairing list zalo
• openclaw pairing approve zalo <CODE>
• Pairing ڈیفالٹ ٹوکن ایکسچینج ہے۔ تفصیلات: Pairing
• channels.zalo.allowFrom عددی یوزر آئی ڈیز قبول کرتا ہے (یوزرنیم لوک اَپ دستیاب نہیں)۔

لانگ پولنگ بمقابلہ ویب ہُک¶

• ڈیفالٹ: لانگ پولنگ (عوامی URL درکار نہیں)۔
• ویب ہُک موڈ: channels.zalo.webhookUrl اور channels.zalo.webhookSecret سیٹ کریں۔
• ویب ہُک سیکرٹ 8-256 حروف کا ہونا لازم ہے۔
• ویب ہُک URL کو HTTPS استعمال کرنا ہوگا۔
• Zalo تصدیق کے لیے X-Bot-Api-Secret-Token ہیڈر کے ساتھ ایونٹس بھیجتا ہے۔
• گیٹ وے HTTP ویب ہُک درخواستیں channels.zalo.webhookPath پر ہینڈل کرتا ہے (بطورِ طے شدہ ویب ہُک URL پاتھ)۔

نوٹ: Zalo API دستاویزات کے مطابق getUpdates (پولنگ) اور ویب ہُک ایک دوسرے کے ساتھ استعمال نہیں ہو سکتے۔

معاون پیغام اقسام¶

• متنی پیغامات: 2000 حروف کی چنکنگ کے ساتھ مکمل معاونت۔
• تصویری پیغامات: آنے والی تصاویر ڈاؤن لوڈ اور پروسیس کریں؛ sendPhoto کے ذریعے تصاویر بھیجیں۔
• اسٹیکرز: لاگ کیے جاتے ہیں مگر مکمل طور پر پروسیس نہیں ہوتے (ایجنٹ کا جواب نہیں)۔
• غیر معاون اقسام: لاگ کیے جاتے ہیں (مثلاً محفوظ صارفین کے پیغامات)۔

صلاحیتیں¶

ترسیلی اہداف (CLI/cron)¶

• ہدف کے طور پر چیٹ آئی ڈی استعمال کریں۔
• مثال: openclaw message send --channel zalo --target 123456789 --message "hi"۔

خرابیوں کا ازالہ¶

بوٹ جواب نہیں دے رہا:

• چیک کریں کہ ٹوکن درست ہے: openclaw channels status --probe
• تصدیق کریں کہ ارسال کنندہ منظور شدہ ہے (pairing یا allowFrom)
• گیٹ وے لاگز چیک کریں: openclaw logs --follow

ویب ہُک ایونٹس موصول نہیں ہو رہے:

• یقینی بنائیں کہ ویب ہُک URL HTTPS استعمال کرتا ہے
• سیکرٹ ٹوکن 8-256 حروف کا ہونے کی تصدیق کریں
• کنفیگر شدہ پاتھ پر گیٹ وے HTTP اینڈ پوائنٹ کی رسائی کی تصدیق کریں
• یہ چیک کریں کہ getUpdates پولنگ چل نہیں رہی (دونوں باہم متضاد ہیں)

کنفیگریشن حوالہ (Zalo)¶

مکمل کنفیگریشن: Configuration

فراہم کنندہ کے اختیارات:

• channels.zalo.enabled: چینل اسٹارٹ اپ کو فعال/غیرفعال کریں۔
• channels.zalo.botToken: Zalo Bot Platform سے بوٹ ٹوکن۔
• channels.zalo.tokenFile: فائل پاتھ سے ٹوکن پڑھیں۔
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled (ڈیفالٹ: pairing)۔
• channels.zalo.allowFrom: DM allowlist (یوزر IDs)۔ open کے لیے "*" درکار ہے۔ وزارڈ عددی IDs طلب کرے گا۔
• channels.zalo.mediaMaxMb: آنے/جانے والے میڈیا کی حد (MB، ڈیفالٹ 5)۔
• channels.zalo.webhookUrl: ویب ہُک موڈ فعال کریں (HTTPS درکار)۔
• channels.zalo.webhookSecret: ویب ہُک سیکرٹ (8-256 حروف)۔
• channels.zalo.webhookPath: گیٹ وے HTTP سرور پر ویب ہُک پاتھ۔
• channels.zalo.proxy: API درخواستوں کے لیے پراکسی URL۔

ملٹی اکاؤنٹ اختیارات:

• channels.zalo.accounts.<id>.botToken`: فی اکاؤنٹ ٹوکن۔
• channels.zalo.accounts.<id>.tokenFile`: فی اکاؤنٹ ٹوکن فائل۔
• channels.zalo.accounts.<id>.name`: ڈسپلے نام۔
• channels.zalo.accounts.<id>.enabled`: اکاؤنٹ فعال/غیر فعال کریں۔
• channels.zalo.accounts.<id>.dmPolicy`: فی اکاؤنٹ DM پالیسی۔
• channels.zalo.accounts.<id>.allowFrom: فی اکاؤنٹ اجازت فہرست۔
• channels.zalo.accounts.<id>.webhookUrl: فی اکاؤنٹ ویب ہُک URL۔
• channels.zalo.accounts.<id>.webhookSecret: فی اکاؤنٹ ویب ہُک خفیہ کلید۔
• channels.zalo.accounts.<id>.webhookPath: فی اکاؤنٹ ویب ہُک راستہ۔
• channels.zalo.accounts.<id>.proxy: فی اکاؤنٹ پراکسی URL۔