> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Zalo

Stato: sperimentale. I DM sono supportati. La sezione [Funzionalità](#capabilities) qui sotto riflette il comportamento attuale dei bot Marketplace.

## Plugin in bundle

Zalo viene distribuito come Plugin in bundle nelle versioni attuali di OpenClaw, quindi le normali build pacchettizzate
non richiedono un'installazione separata.

Se usi una build precedente o un'installazione personalizzata che esclude Zalo, installa direttamente il
pacchetto npm:

* Installa tramite CLI: `openclaw plugins install @openclaw/zalo`
* Versione fissata: `openclaw plugins install @openclaw/zalo@2026.5.2`
* Oppure da un checkout sorgente: `openclaw plugins install ./path/to/local/zalo-plugin`
* Dettagli: [Plugin](/it/tools/plugin)

## Configurazione rapida (principianti)

1. Assicurati che il Plugin Zalo sia disponibile.
   * Le versioni pacchettizzate attuali di OpenClaw lo includono già.
   * Le installazioni precedenti/personalizzate possono aggiungerlo manualmente con i comandi sopra.
2. Imposta il token:
   * Env: `ZALO_BOT_TOKEN=...`
   * Oppure configurazione: `channels.zalo.accounts.default.botToken: "..."`.
3. Riavvia il gateway (o completa la configurazione).
4. L'accesso DM usa il pairing per impostazione predefinita; approva il codice di pairing al primo contatto.

Configurazione minima:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}
```

## Che cos'è

Zalo è un'app di messaggistica orientata al Vietnam; la sua Bot API consente al Gateway di eseguire un bot per conversazioni 1:1.
È adatta per supporto o notifiche quando vuoi un routing deterministico verso Zalo.

Questa pagina riflette il comportamento attuale di OpenClaw per i **bot Zalo Bot Creator / Marketplace**.
I **bot Zalo Official Account (OA)** sono una superficie di prodotto Zalo diversa e potrebbero comportarsi diversamente.

* Un canale Zalo Bot API posseduto dal Gateway.
* Routing deterministico: le risposte tornano a Zalo; il modello non sceglie mai i canali.
* I DM condividono la sessione principale dell'agente.
* La sezione [Funzionalità](#capabilities) qui sotto mostra il supporto attuale dei bot Marketplace.

## Configurazione (percorso rapido)

### 1) Crea un token bot (Zalo Bot Platform)

1. Vai su [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) e accedi.
2. Crea un nuovo bot e configura le sue impostazioni.
3. Copia il token bot completo (in genere `numeric_id:secret`). Per i bot Marketplace, il token runtime utilizzabile potrebbe comparire nel messaggio di benvenuto del bot dopo la creazione.

### 2) Configura il token (env o configurazione)

Esempio:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}
```

Se in seguito passi a una superficie bot Zalo in cui i gruppi sono disponibili, puoi aggiungere esplicitamente configurazioni specifiche per i gruppi come `groupPolicy` e `groupAllowFrom`. Per il comportamento attuale dei bot Marketplace, vedi [Funzionalità](#capabilities).

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.

3. Riavvia il gateway. Zalo si avvia quando viene risolto un token (env o configurazione).
4. L'accesso DM usa il pairing per impostazione predefinita. Approva il codice quando il bot viene contattato per la prima volta.

## Come funziona (comportamento)

* I messaggi in ingresso vengono normalizzati nella busta di canale condivisa con placeholder per i media.
* Le risposte vengono sempre instradate alla stessa chat Zalo.
* Long polling per impostazione predefinita; modalità Webhook disponibile con `channels.zalo.webhookUrl`.

## Limiti

* Il testo in uscita viene suddiviso in blocchi da 2000 caratteri (limite API Zalo).
* Download/upload dei media sono limitati da `channels.zalo.mediaMaxMb` (predefinito 5).
* Lo streaming è bloccato per impostazione predefinita perché il limite di 2000 caratteri rende lo streaming meno utile.

## Controllo accessi (DM)

### Accesso DM

* Predefinito: `channels.zalo.dmPolicy = "pairing"`. I mittenti sconosciuti ricevono un codice di pairing; i messaggi vengono ignorati finché non vengono approvati (i codici scadono dopo 1 ora).
* Approva tramite:
  * `openclaw pairing list zalo`
  * `openclaw pairing approve zalo <CODE>`
* Il pairing è lo scambio token predefinito. Dettagli: [Pairing](/it/channels/pairing)
* `channels.zalo.allowFrom` accetta ID utente numerici (non è disponibile la ricerca per nome utente).

## Controllo accessi (gruppi)

Per i **bot Zalo Bot Creator / Marketplace**, il supporto gruppi non era disponibile in pratica perché il bot non poteva essere aggiunto a nessun gruppo.

Questo significa che le chiavi di configurazione relative ai gruppi qui sotto esistono nello schema, ma non erano utilizzabili per i bot Marketplace:

* `channels.zalo.groupPolicy` controlla la gestione dei messaggi in ingresso nei gruppi: `open | allowlist | disabled`.
* `channels.zalo.groupAllowFrom` limita quali ID mittente possono attivare il bot nei gruppi.
* Se `groupAllowFrom` non è impostato, Zalo ripiega su `allowFrom` per i controlli del mittente.
* Nota runtime: se `channels.zalo` manca completamente, il runtime ripiega comunque su `groupPolicy="allowlist"` per sicurezza.

I valori della policy di gruppo (quando l'accesso ai gruppi è disponibile sulla tua superficie bot) sono:

* `groupPolicy: "disabled"` — blocca tutti i messaggi di gruppo.
* `groupPolicy: "open"` — consente qualsiasi membro del gruppo (vincolato alla menzione).
* `groupPolicy: "allowlist"` — impostazione predefinita fail-closed; sono accettati solo i mittenti consentiti.

Se usi una superficie di prodotto bot Zalo diversa e hai verificato un comportamento dei gruppi funzionante, documentalo separatamente invece di presumere che corrisponda al flusso dei bot Marketplace.

## Long polling vs Webhook

* Predefinito: long polling (nessun URL pubblico richiesto).
* Modalità Webhook: imposta `channels.zalo.webhookUrl` e `channels.zalo.webhookSecret`.
  * Il segreto Webhook deve essere di 8-256 caratteri.
  * L'URL Webhook deve usare HTTPS.
  * Zalo invia eventi con l'intestazione `X-Bot-Api-Secret-Token` per la verifica.
  * L'HTTP del Gateway gestisce le richieste Webhook in `channels.zalo.webhookPath` (per impostazione predefinita il percorso dell'URL Webhook).
  * Le richieste devono usare `Content-Type: application/json` (o tipi media `+json`).
  * Gli eventi duplicati (`event_name + message_id`) vengono ignorati per una breve finestra di replay.
  * Il traffico a raffica è soggetto a rate limit per percorso/origine e può restituire HTTP 429.

**Nota:** getUpdates (polling) e Webhook si escludono a vicenda secondo la documentazione API Zalo.

## Tipi di messaggi supportati

Per una rapida panoramica del supporto, vedi [Funzionalità](#capabilities). Le note qui sotto aggiungono dettagli dove il comportamento richiede ulteriore contesto.

* **Messaggi di testo**: supporto completo con suddivisione in blocchi da 2000 caratteri.
* **URL semplici nel testo**: si comportano come normale input testuale.
* **Anteprime link / schede link avanzate**: vedi lo stato dei bot Marketplace in [Funzionalità](#capabilities); non attivavano in modo affidabile una risposta.
* **Messaggi immagine**: vedi lo stato dei bot Marketplace in [Funzionalità](#capabilities); la gestione delle immagini in ingresso era inaffidabile (indicatore di digitazione senza risposta finale).
* **Sticker**: vedi lo stato dei bot Marketplace in [Funzionalità](#capabilities).
* **Note vocali / file audio / video / allegati file generici**: vedi lo stato dei bot Marketplace in [Funzionalità](#capabilities).
* **Tipi non supportati**: registrati nei log (per esempio, messaggi da utenti protetti).

## Funzionalità

Questa tabella riassume il comportamento attuale dei **bot Zalo Bot Creator / Marketplace** in OpenClaw.

| Funzionalità                 | Stato                                            |
| ---------------------------- | ------------------------------------------------ |
| Messaggi diretti             | ✅ Supportati                                     |
| Gruppi                       | ❌ Non disponibili per i bot Marketplace          |
| Media (immagini in ingresso) | ⚠️ Limitato / verifica nel tuo ambiente          |
| Media (immagini in uscita)   | ⚠️ Non ritestato per i bot Marketplace           |
| URL semplici nel testo       | ✅ Supportati                                     |
| Anteprime link               | ⚠️ Inaffidabili per i bot Marketplace            |
| Reazioni                     | ❌ Non supportate                                 |
| Sticker                      | ⚠️ Nessuna risposta agente per i bot Marketplace |
| Note vocali / audio / video  | ⚠️ Nessuna risposta agente per i bot Marketplace |
| Allegati file                | ⚠️ Nessuna risposta agente per i bot Marketplace |
| Thread                       | ❌ Non supportati                                 |
| Sondaggi                     | ❌ Non supportati                                 |
| Comandi nativi               | ❌ Non supportati                                 |
| Streaming                    | ⚠️ Bloccato (limite di 2000 caratteri)           |

## Destinazioni di consegna (CLI/cron)

* Usa un ID chat come destinazione.
* Esempio: `openclaw message send --channel zalo --target 123456789 --message "hi"`.

## Risoluzione dei problemi

**Il bot non risponde:**

* Controlla 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 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
* Controlla che il polling getUpdates non sia in esecuzione (si escludono a vicenda)

## Riferimento configurazione (Zalo)

Configurazione completa: [Configurazione](/it/gateway/configuration)

Le chiavi piatte di primo livello (`channels.zalo.botToken`, `channels.zalo.dmPolicy` e simili) sono una scorciatoia legacy per account singolo. Preferisci `channels.zalo.accounts.<id>.*` per le nuove configurazioni. Entrambe le forme sono ancora documentate qui perché esistono nello schema.

Opzioni provider:

* `channels.zalo.enabled`: abilita/disabilita l'avvio del canale.
* `channels.zalo.botToken`: token bot da Zalo Bot Platform.
* `channels.zalo.tokenFile`: legge 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 `"*"`. La procedura guidata chiederà ID numerici.
* `channels.zalo.groupPolicy`: `open | allowlist | disabled` (predefinito: allowlist). Presente nella configurazione; vedi [Funzionalità](#capabilities) e [Controllo accessi (gruppi)](#access-control-groups) per il comportamento attuale dei bot Marketplace.
* `channels.zalo.groupAllowFrom`: allowlist dei mittenti di gruppo (ID utente). Ripiega su `allowFrom` quando non impostato.
* `channels.zalo.mediaMaxMb`: limite media in ingresso/uscita (MB, predefinito 5).
* `channels.zalo.webhookUrl`: abilita la modalità Webhook (HTTPS richiesto).
* `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 l'account.
* `channels.zalo.accounts.<id>.dmPolicy`: policy DM per account.
* `channels.zalo.accounts.<id>.allowFrom`: allowlist per account.
* `channels.zalo.accounts.<id>.groupPolicy`: policy di gruppo per account. Presente nella configurazione; vedi [Funzionalità](#capabilities) e [Controllo accessi (gruppi)](#access-control-groups) per il comportamento attuale dei bot Marketplace.
* `channels.zalo.accounts.<id>.groupAllowFrom`: allowlist dei mittenti di gruppo 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.

## Correlati

* [Panoramica canali](/it/channels) — tutti i canali supportati
* [Pairing](/it/channels/pairing) — autenticazione DM e flusso di pairing
* [Gruppi](/it/channels/groups) — comportamento delle chat di gruppo e gating tramite menzione
* [Routing canali](/it/channels/channel-routing) — routing delle sessioni per i messaggi
* [Sicurezza](/it/gateway/security) — modello di accesso e hardening