Zalo

​

Plugin incluso

• 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).

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

​

Che cos’è

​

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

• 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)

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

​

Risoluzione dei problemi

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

• 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

​

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