Zalo (Bot API)

Stato: sperimentale. I DM sono supportati; la gestione dei gruppi e disponibile con controlli espliciti sulla policy di gruppo.

Plugin necessario

Zalo e distribuito come plugin e non e incluso nell’installazione core.

Installa da CLI: openclaw plugins install @openclaw/zalo
Oppure seleziona Zalo durante l’onboarding e conferma il prompt di installazione
Dettagli: Plugin

Setup rapido (principianti)

Installa il plugin Zalo:
- Da un checkout sorgente: openclaw plugins install ./extensions/zalo
- Da npm (se pubblicato): openclaw plugins install @openclaw/zalo
- Oppure scegli Zalo nell’onboarding e conferma il prompt di installazione
Imposta il token:
- Env: ZALO_BOT_TOKEN=...
- Oppure config: channels.zalo.botToken: "...".
Riavvia il gateway (o completa l’onboarding).
L’accesso DM e in pairing per impostazione predefinita; approva il codice di pairing al primo contatto.

Configurazione minimale:

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

Cos’e

Zalo e un’app di messaggistica focalizzata sul Vietnam; la sua Bot API permette al Gateway di gestire un bot per conversazioni 1:1. E indicata per supporto o notifiche dove vuoi un routing deterministico verso Zalo.

Un canale Zalo Bot API gestito dal Gateway.
Routing deterministico: le risposte tornano a Zalo; il modello non sceglie mai i canali.
I DM condividono la sessione principale dell’agent.
I gruppi sono supportati con controlli sulla policy (groupPolicy + groupAllowFrom) e il comportamento predefinito e fail-closed con allowlist.

Setup (percorso rapido)

1) Crea un token bot (Zalo Bot Platform)

Vai su https://bot.zaloplatforms.com e accedi.
Crea un nuovo bot e configura le sue impostazioni.
Copia il token del bot (formato: 12345689:abc-xyz).

2) Configura il token (env o config)

Esempio:

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

Opzione env: ZALO_BOT_TOKEN=... (funziona solo per l’account predefinito).

Supporto multi-account: usa channels.zalo.accounts con token per account e name opzionale.

Riavvia il gateway. Zalo si avvia quando un token viene risolto (env o config).
L’accesso DM e in pairing per impostazione predefinita. Approva il codice quando il bot viene contattato la prima volta.

Come funziona (comportamento)

I messaggi in ingresso vengono normalizzati nell’envelope condiviso del canale con placeholder per i media.
Le risposte vengono sempre instradate verso la stessa chat Zalo.
Long-polling per impostazione predefinita; modalita webhook disponibile con channels.zalo.webhookUrl.

Limiti

Il testo in uscita viene segmentato a 2000 caratteri (limite API Zalo).
I download/upload di media sono limitati da channels.zalo.mediaMaxMb (predefinito 5).
Lo streaming e bloccato per impostazione predefinita a causa del limite di 2000 caratteri che rende lo streaming poco utile.

Controllo degli accessi (DM)

Accesso DM

Predefinito: channels.zalo.dmPolicy = "pairing". I mittenti sconosciuti ricevono un codice di pairing; i messaggi sono ignorati fino all’approvazione (i codici scadono dopo 1 ora).
Approvazione tramite:
- openclaw pairing list zalo
- openclaw pairing approve zalo <CODE>
Il pairing e lo scambio token predefinito. Dettagli: Pairing
channels.zalo.allowFrom accetta ID utente numerici (nessun lookup per username disponibile).

Controllo degli accessi (Gruppi)

channels.zalo.groupPolicy controlla la gestione dei gruppi in ingresso: open | allowlist | disabled.
Il comportamento predefinito e fail-closed: allowlist.
channels.zalo.groupAllowFrom limita quali ID mittente possono attivare il bot nei gruppi.
Se groupAllowFrom non e impostato, Zalo usa allowFrom come fallback per i controlli sui mittenti.
groupPolicy: "disabled" blocca tutti i messaggi di gruppo.
groupPolicy: "open" consente qualsiasi membro del gruppo (con gating menzione).
Nota runtime: se channels.zalo manca completamente, il runtime usa comunque groupPolicy="allowlist" per sicurezza.

Long-polling vs webhook

Predefinito: long-polling (nessun URL pubblico necessario).
Modalita webhook: imposta channels.zalo.webhookUrl e channels.zalo.webhookSecret.
- Il segreto del webhook deve essere di 8-256 caratteri.
- L’URL del webhook deve usare HTTPS.
- Zalo invia eventi con header X-Bot-Api-Secret-Token per la verifica.
- Il gateway HTTP gestisce le richieste webhook su channels.zalo.webhookPath (predefinito: il percorso dell’URL del webhook).
- Le richieste devono usare Content-Type: application/json (o media type +json).
- Gli eventi duplicati (event_name + message_id) vengono ignorati per una breve finestra di replay.
- Il traffico burst e limitato per percorso/sorgente e puo restituire HTTP 429.

Nota: getUpdates (polling) e webhook sono mutuamente esclusivi secondo la documentazione dell’API Zalo.

Tipi di messaggi supportati

Messaggi di testo: supporto completo con segmentazione a 2000 caratteri.
Messaggi immagine: download e elaborazione immagini in ingresso; invio immagini tramite sendPhoto.
Sticker: registrati nei log ma non completamente elaborati (nessuna risposta dell’agent).
Tipi non supportati: registrati nei log (es. messaggi da utenti protetti).

Funzionalita

Funzionalita	Stato
Messaggi diretti	Supportati
Gruppi	Supportati con controlli policy (allowlist per impostazione predefinita)
Media (immagini)	Supportati
Reazioni	Non supportate
Thread	Non supportati
Sondaggi	Non supportati
Comandi nativi	Non supportati
Streaming	Bloccato (limite 2000 caratteri)

Target di consegna (CLI/cron)

Usa un ID chat come target.
Esempio: openclaw message send --channel zalo --target 123456789 --message "ciao".

Risoluzione problemi

Il bot non risponde:

Verifica che il token sia valido: openclaw channels status --probe
Verifica che il mittente sia approvato (pairing o allowFrom)
Controlla i log del gateway: openclaw logs --follow

Il webhook non riceve eventi:

Assicurati che l’URL del webhook usi HTTPS
Verifica che il token segreto sia di 8-256 caratteri
Conferma che l’endpoint HTTP del gateway sia raggiungibile sul percorso configurato
Verifica che il polling getUpdates non sia in esecuzione (sono mutuamente esclusivi)

Riferimento configurazione (Zalo)

Configurazione completa: Configurazione

Opzioni del provider:

channels.zalo.enabled: abilita/disabilita l’avvio del canale.
channels.zalo.botToken: token bot dalla Zalo Bot Platform.
channels.zalo.tokenFile: leggi il token da un percorso file regolare. I symlink sono rifiutati.
channels.zalo.dmPolicy: pairing | allowlist | open | disabled (predefinito: pairing).
channels.zalo.allowFrom: allowlist DM (ID utente). open richiede "*". Il wizard chiede ID numerici.
channels.zalo.groupPolicy: open | allowlist | disabled (predefinito: allowlist).
channels.zalo.groupAllowFrom: allowlist mittenti gruppi (ID utente). Fallback su allowFrom se non impostato.
channels.zalo.mediaMaxMb: limite media in ingresso/uscita (MB, predefinito 5).
channels.zalo.webhookUrl: abilita la modalita webhook (HTTPS obbligatorio).
channels.zalo.webhookSecret: segreto webhook (8-256 caratteri).
channels.zalo.webhookPath: percorso webhook sul server HTTP del gateway.
channels.zalo.proxy: URL proxy per le richieste API.

Opzioni multi-account:

channels.zalo.accounts.<id>.botToken: token per account.
channels.zalo.accounts.<id>.tokenFile: file token regolare per account. I symlink sono rifiutati.
channels.zalo.accounts.<id>.name: nome visualizzato.
channels.zalo.accounts.<id>.enabled: abilita/disabilita account.
channels.zalo.accounts.<id>.dmPolicy: policy DM per account.
channels.zalo.accounts.<id>.allowFrom: allowlist per account.
channels.zalo.accounts.<id>.groupPolicy: policy gruppi per account.
channels.zalo.accounts.<id>.groupAllowFrom: allowlist mittenti gruppi per account.
channels.zalo.accounts.<id>.webhookUrl: URL webhook per account.
channels.zalo.accounts.<id>.webhookSecret: segreto webhook per account.
channels.zalo.accounts.<id>.webhookPath: percorso webhook per account.
channels.zalo.accounts.<id>.proxy: URL proxy per account.