Zalo

Stato: sperimentale. Sono implementati sia i messaggi diretti sia le chat di gruppo; la tabella delle funzionalità seguente riflette il comportamento verificato sui bot Zalo Bot Creator / Marketplace.

Plugin incluso

Zalo viene distribuito come Plugin incluso nelle versioni correnti di OpenClaw, quindi le build pacchettizzate non richiedono un'installazione separata.

In una build meno recente o in un'installazione personalizzata che esclude Zalo, installa direttamente il pacchetto npm:

• Installazione: openclaw plugins install @openclaw/zalo
• Versione fissata: openclaw plugins install @openclaw/zalo@2026.6.11
• Da un checkout locale: openclaw plugins install ./path/to/local/zalo-plugin
• Dettagli: Plugin

Configurazione rapida

1. Crea un token per il bot su https://bot.zaloplatforms.com (accedi, crea un bot, configura le impostazioni). Il token ha il formato numeric_id:secret; per i bot Marketplace, il token utilizzabile in fase di esecuzione può apparire nel messaggio di benvenuto del bot.
2. Imposta il token, tramite la variabile di ambiente ZALO_BOT_TOKEN=... (solo per l'account predefinito) oppure nella configurazione.
3. Riavvia il Gateway.
4. Approva il codice di associazione al primo contatto tramite messaggio diretto (il criterio predefinito per i messaggi diretti è l'associazione).

Configurazione minima:

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

Account multipli: aggiungi altre voci in channels.zalo.accounts.<id>, ciascuna con i propri botToken/name. channels.zalo.botToken (struttura piatta, senza accounts) è una forma abbreviata legacy per un singolo account; per le nuove configurazioni, preferisci accounts.<id>.*.

Che cos'è

Zalo è un'app di messaggistica orientata al mercato vietnamita. La sua API per bot consente al Gateway di eseguire un bot sia per conversazioni individuali sia per chat di gruppo, con instradamento deterministico verso Zalo (il modello non sceglie mai i canali).

Questa pagina tratta i bot Zalo Bot Creator / Marketplace. I bot Zalo Official Account (OA) costituiscono una superficie di prodotto diversa e possono comportarsi diversamente; questa pagina non li tratta.

Funzionamento

• I messaggi in entrata vengono normalizzati nell'involucro condiviso del canale con segnaposto per i contenuti multimediali.
• Le risposte vengono sempre instradate alla stessa chat Zalo; la risposta con citazione non viene utilizzata (replyToMode è disattivato in modo fisso).
• Per impostazione predefinita viene usato il long polling (getUpdates); la modalità Webhook è disponibile tramite channels.zalo.webhookUrl.
• Nei gruppi è necessaria una @menzione per attivare il bot; questa impostazione non è configurabile per singolo canale.

Limiti

Controllo degli accessi

Messaggi diretti

• channels.zalo.dmPolicy: pairing (predefinito) | allowlist | open | disabled.
• Associazione: i mittenti sconosciuti ricevono un codice di associazione; i messaggi vengono ignorati fino all'approvazione. I codici scadono dopo 1 ora.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Dettagli: Associazione
• channels.zalo.allowFrom accetta ID utente Zalo numerici (nessuna ricerca per nome utente). open richiede "*".

Gruppi

Le chat di gruppo sono supportate dal Plugin (chatTypes: ["direct", "group"]) e sono subordinate alla menzione e al criterio per i gruppi:

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom limita gli ID dei mittenti che possono attivare il bot nei gruppi; se non è impostato, usa allowFrom.
• Risoluzione predefinita: quando channels.zalo è configurato, un groupPolicy non impostato viene risolto in open. Quando channels.zalo è completamente assente, l'esecuzione adotta una modalità chiusa e usa allowlist.
• Avvertenza segnalata nell'uso reale: in alcune configurazioni di bot Marketplace non è stato possibile aggiungere il bot a un gruppo. Se riscontri questo problema, verifica le impostazioni del bot nella Zalo Bot Platform; si tratta di un vincolo della piattaforma, non di un criterio di OpenClaw.

Long polling e Webhook

• Impostazione predefinita: long polling (non è richiesto un URL pubblico).
• Modalità Webhook: imposta channels.zalo.webhookUrl e channels.zalo.webhookSecret.
  • L'URL del Webhook deve usare HTTPS.
  • Il segreto del Webhook deve contenere da 8 a 256 caratteri.
  • Zalo invia gli eventi con un'intestazione X-Bot-Api-Secret-Token, verificata con un confronto a tempo costante.
  • Il server HTTP del Gateway gestisce le richieste Webhook nel percorso channels.zalo.webhookPath (per impostazione predefinita, il percorso dell'URL del Webhook).
  • Le richieste devono usare Content-Type: application/json (oppure un tipo di contenuto multimediale +json).
  • Secondo la documentazione dell'API Zalo, il polling getUpdates e il Webhook si escludono a vicenda.

Tipi di messaggio supportati

• Testo: supporto completo, suddiviso in blocchi di 2000 caratteri.
• Contenuti multimediali: in entrata e in uscita, limitati da mediaMaxMb.
• Reazioni, thread, sondaggi, comandi nativi: non supportati dal Plugin.
• Streaming: il Plugin dichiara la funzionalità di streaming a blocchi, ma Zalo non dispone di opzioni dedicate per la coda in uscita o la regolazione dell'unione del testo (a differenza di alcuni altri canali regionali); se questo aspetto è importante per il tuo caso d'uso, verifica il comportamento corrente nel tuo ambiente.

Funzionalità

Destinazioni di consegna (CLI/Cron)

Usa un ID chat come destinazione:

openclaw message send --channel zalo --target 123456789 --message "hi"

Risoluzione dei problemi

Il bot non risponde:

• Controlla il token: openclaw channels status --probe
• Verifica che il mittente sia approvato (associazione o allowFrom)
• Controlla i log del Gateway: openclaw logs --follow

Il Webhook non riceve eventi:

• Verifica che l'URL del Webhook usi HTTPS
• Verifica che il segreto contenga da 8 a 256 caratteri
• Verifica che l'endpoint HTTP del Gateway sia raggiungibile nel percorso configurato
• Verifica che il polling getUpdates non sia anch'esso in esecuzione (si escludono a vicenda)
• Un picco di richieste può restituire HTTP 429 (120 richieste / 60 s per percorso+IP); attendi e riprova

Riferimento della configurazione

Configurazione completa: Configurazione

channels.zalo.botToken, channels.zalo.dmPolicy e le altre chiavi piatte di primo livello sono la forma abbreviata legacy per singolo account dei campi precedenti; entrambe le forme sono supportate.

Opzione di ambiente: ZALO_BOT_TOKEN=... risolve soltanto il token dell'account predefinito.

Argomenti correlati

• Panoramica dei canali - tutti i canali supportati
• Associazione - autenticazione dei messaggi diretti e flusso di associazione
• Gruppi - comportamento delle chat di gruppo e attivazione tramite menzione
• Instradamento dei canali - instradamento delle sessioni per i messaggi
• Sicurezza - modello di accesso e rafforzamento della sicurezza