​

Zalo (Bot API)

​

Plugin bawaan

• Instal melalui CLI: openclaw plugins install @openclaw/zalo
• Atau dari checkout sumber: openclaw plugins install ./path/to/local/zalo-plugin
• Detail: Plugins

​

Penyiapan cepat (pemula)

1. Pastikan plugin Zalo tersedia.
   • Rilis OpenClaw paket saat ini sudah menyertakan plugin ini.
   • Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Atur token:
   • Env: ZALO_BOT_TOKEN=...
   • Atau konfigurasi: channels.zalo.accounts.default.botToken: "...".
3. Mulai ulang gateway (atau selesaikan penyiapan).
4. Akses DM secara default menggunakan pairing; setujui kode pairing saat kontak pertama.

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

​

Apa itu

• Channel Zalo Bot API yang dimiliki oleh Gateway.
• Perutean deterministik: balasan kembali ke Zalo; model tidak pernah memilih channel.
• DM berbagi sesi utama agen.
• Bagian Kemampuan di bawah menunjukkan dukungan bot Marketplace saat ini.

​

Penyiapan (jalur cepat)

​

1) Buat token bot (Zalo Bot Platform)

1. Buka https://bot.zaloplatforms.com dan masuk.
2. Buat bot baru dan konfigurasikan pengaturannya.
3. Salin token bot lengkap (biasanya numeric_id:secret). Untuk bot Marketplace, token runtime yang dapat digunakan mungkin muncul dalam pesan sambutan bot setelah pembuatan.

​

2) Konfigurasikan token (env atau config)

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

3. Mulai ulang gateway. Zalo dimulai saat token berhasil di-resolve (env atau config).
4. Akses DM secara default menggunakan pairing. Setujui kode saat bot pertama kali dihubungi.

​

Cara kerjanya (perilaku)

• Pesan masuk dinormalisasi ke envelope channel bersama dengan placeholder media.
• Balasan selalu dirutekan kembali ke chat Zalo yang sama.
• Long-polling secara default; mode webhook tersedia dengan channels.zalo.webhookUrl.

​

Batasan

• Teks keluar dipotong menjadi 2000 karakter (batas API Zalo).
• Unduhan/unggahan media dibatasi oleh channels.zalo.mediaMaxMb (default 5).
• Streaming diblokir secara default karena batas 2000 karakter membuat streaming kurang berguna.

​

Kontrol akses (DM)

​

Akses DM

• Default: channels.zalo.dmPolicy = "pairing". Pengirim yang tidak dikenal menerima kode pairing; pesan diabaikan sampai disetujui (kode kedaluwarsa setelah 1 jam).
• Setujui melalui:
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
• Pairing adalah pertukaran token default. Detail: Pairing
• channels.zalo.allowFrom menerima ID pengguna numerik (tidak ada pencarian username yang tersedia).

​

Kontrol akses (Grup)

• channels.zalo.groupPolicy mengontrol penanganan masuk grup: open | allowlist | disabled.
• channels.zalo.groupAllowFrom membatasi ID pengirim mana yang dapat memicu bot di grup.
• Jika groupAllowFrom tidak diatur, Zalo menggunakan fallback ke allowFrom untuk pemeriksaan pengirim.
• Catatan runtime: jika channels.zalo sama sekali tidak ada, runtime tetap menggunakan fallback ke groupPolicy="allowlist" demi keamanan.

• groupPolicy: "disabled" — memblokir semua pesan grup.
• groupPolicy: "open" — mengizinkan anggota grup mana pun (dibatasi mention).
• groupPolicy: "allowlist" — default fail-closed; hanya pengirim yang diizinkan yang diterima.

​

Long-polling vs webhook

• Default: long-polling (tidak memerlukan URL publik).
• Mode webhook: atur channels.zalo.webhookUrl dan channels.zalo.webhookSecret.
  • Rahasia webhook harus 8-256 karakter.
  • URL webhook harus menggunakan HTTPS.
  • Zalo mengirim peristiwa dengan header X-Bot-Api-Secret-Token untuk verifikasi.
  • HTTP Gateway menangani permintaan webhook di channels.zalo.webhookPath (default ke path URL webhook).
  • Permintaan harus menggunakan Content-Type: application/json (atau tipe media +json).
  • Peristiwa duplikat (event_name + message_id) diabaikan selama jendela replay singkat.
  • Lonjakan trafik dibatasi lajunya per path/sumber dan dapat mengembalikan HTTP 429.

​

Jenis pesan yang didukung

• Pesan teks: Dukungan penuh dengan pemotongan 2000 karakter.
• URL polos dalam teks: Berperilaku seperti input teks normal.
• Pratinjau tautan / kartu tautan rich: Lihat status bot Marketplace di Kemampuan; fitur ini tidak secara andal memicu balasan.
• Pesan gambar: Lihat status bot Marketplace di Kemampuan; penanganan gambar masuk tidak andal (indikator mengetik tanpa balasan akhir).
• Stiker: Lihat status bot Marketplace di Kemampuan.
• Catatan suara / file audio / video / lampiran file umum: Lihat status bot Marketplace di Kemampuan.
• Jenis yang tidak didukung: Dicatat di log (misalnya, pesan dari pengguna yang dilindungi).

​

Kemampuan

​

Target pengiriman (CLI/cron)

• Gunakan chat id sebagai target.
• Contoh: openclaw message send --channel zalo --target 123456789 --message "hi".

​

Pemecahan masalah

• Periksa apakah token valid: openclaw channels status --probe
• Pastikan pengirim telah disetujui (pairing atau allowFrom)
• Periksa log gateway: openclaw logs --follow

• Pastikan URL webhook menggunakan HTTPS
• Pastikan token rahasia 8-256 karakter
• Konfirmasikan endpoint HTTP gateway dapat dijangkau pada path yang dikonfigurasi
• Periksa bahwa polling getUpdates tidak sedang berjalan (keduanya saling eksklusif)

​

Referensi konfigurasi (Zalo)

• channels.zalo.enabled: aktifkan/nonaktifkan startup channel.
• channels.zalo.botToken: token bot dari Zalo Bot Platform.
• channels.zalo.tokenFile: baca token dari path file reguler. Symlink ditolak.
• channels.zalo.dmPolicy: pairing | allowlist | open | disabled (default: pairing).
• channels.zalo.allowFrom: allowlist DM (ID pengguna). open mengharuskan "*". Wizard akan meminta ID numerik.
• channels.zalo.groupPolicy: open | allowlist | disabled (default: allowlist). Ada dalam config; lihat Kemampuan dan Kontrol akses (Grup) untuk perilaku bot Marketplace saat ini.
• channels.zalo.groupAllowFrom: allowlist pengirim grup (ID pengguna). Menggunakan fallback ke allowFrom saat tidak diatur.
• channels.zalo.mediaMaxMb: batas media masuk/keluar (MB, default 5).
• channels.zalo.webhookUrl: aktifkan mode webhook (HTTPS wajib).
• channels.zalo.webhookSecret: rahasia webhook (8-256 karakter).
• channels.zalo.webhookPath: path webhook pada server HTTP gateway.
• channels.zalo.proxy: URL proxy untuk permintaan API.

• channels.zalo.accounts.<id>.botToken: token per akun.
• channels.zalo.accounts.<id>.tokenFile: file token reguler per akun. Symlink ditolak.
• channels.zalo.accounts.<id>.name: nama tampilan.
• channels.zalo.accounts.<id>.enabled: aktifkan/nonaktifkan akun.
• channels.zalo.accounts.<id>.dmPolicy: kebijakan DM per akun.
• channels.zalo.accounts.<id>.allowFrom: allowlist per akun.
• channels.zalo.accounts.<id>.groupPolicy: kebijakan grup per akun. Ada dalam config; lihat Kemampuan dan Kontrol akses (Grup) untuk perilaku bot Marketplace saat ini.
• channels.zalo.accounts.<id>.groupAllowFrom: allowlist pengirim grup per akun.
• channels.zalo.accounts.<id>.webhookUrl: URL webhook per akun.
• channels.zalo.accounts.<id>.webhookSecret: rahasia webhook per akun.
• channels.zalo.accounts.<id>.webhookPath: path webhook per akun.
• channels.zalo.accounts.<id>.proxy: URL proxy per akun.

​

Terkait

• Ikhtisar Channel — semua channel yang didukung
• Pairing — autentikasi DM dan alur pairing
• Grup — perilaku chat grup dan penyaringan mention
• Perutean Channel — perutean sesi untuk pesan
• Keamanan — model akses dan hardening