WhatsApp

Stato: pronto per la produzione tramite WhatsApp Web (Baileys). Il Gateway gestisce le sessioni collegate.

# Installazione (su richiesta)

• Onboarding (openclaw onboard) e openclaw channels add --channel whatsapp chiedono di installare il plugin WhatsApp la prima volta che lo selezioni.
• Anche openclaw channels login --channel whatsapp offre il flusso di installazione quando il plugin non è ancora presente.
• Canale dev + checkout git: usa per impostazione predefinita il percorso del plugin locale.
• Stable/Beta: usa il pacchetto npm @openclaw/whatsapp sul tag di rilascio ufficiale corrente.

L'installazione manuale resta disponibile:

openclaw plugins install @openclaw/whatsapp

Usa il pacchetto senza versione per seguire il tag di rilascio ufficiale corrente. Fissa una versione esatta solo quando hai bisogno di un'installazione riproducibile.

Su Windows, il plugin WhatsApp richiede Git in PATH durante l'installazione npm perché una delle sue dipendenze Baileys/libsignal viene recuperata da un URL git. Installa Git for Windows, quindi riavvia la shell ed esegui di nuovo l'installazione:

winget install --id Git.Git -e

Anche Portable Git funziona se la sua directory bin è in PATH.

# Configurazione rapida

{
channels: {
whatsapp: {
  dmPolicy: "pairing",
  allowFrom: ["+15551234567"],
  groupPolicy: "allowlist",
  groupAllowFrom: ["+15551234567"],
},
},
}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# Pattern di distribuzione

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

# Modello runtime

• Il Gateway gestisce il socket WhatsApp e il ciclo di riconnessione.
• Il watchdog di riconnessione usa l'attività del trasporto WhatsApp Web, non solo il volume dei messaggi app in ingresso, quindi una sessione silenziosa di un dispositivo collegato non viene riavviata solo perché nessuno ha inviato messaggi di recente. Un limite più lungo di silenzio dell'applicazione forza comunque una riconnessione se i frame di trasporto continuano ad arrivare ma non vengono gestiti messaggi dell'applicazione durante la finestra del watchdog; dopo una riconnessione transitoria per una sessione attiva di recente, quel controllo del silenzio dell'applicazione usa il timeout normale dei messaggi per la prima finestra di recupero.
• I timing del socket Baileys sono espliciti sotto web.whatsapp.*: keepAliveIntervalMs controlla i ping dell'applicazione WhatsApp Web, connectTimeoutMs controlla il timeout dell'handshake di apertura e defaultQueryTimeoutMs controlla i timeout delle query Baileys.
• Gli invii in uscita richiedono un listener WhatsApp attivo per l'account di destinazione.
• Gli invii ai gruppi allegano metadati di menzione nativi per i token @+<digits> e @<digits> nel testo e nelle didascalie dei media quando il token corrisponde ai metadati correnti dei partecipanti WhatsApp, inclusi i gruppi basati su LID.
• Le chat di stato e broadcast vengono ignorate (@status, @broadcast).
• Il watchdog di riconnessione segue l'attività del trasporto WhatsApp Web, non solo il volume dei messaggi app in ingresso: le sessioni silenziose dei dispositivi collegati restano attive mentre i frame di trasporto continuano, ma uno stallo del trasporto forza la riconnessione molto prima del percorso successivo di disconnessione remota.
• Le chat dirette usano le regole di sessione DM (session.dmScope; il valore predefinito main collassa i DM nella sessione principale dell'agente).
• Le sessioni di gruppo sono isolate (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters possono essere destinazioni in uscita esplicite con il loro JID nativo @newsletter. Gli invii in uscita alle newsletter usano i metadati di sessione del canale (agent:<agentId>:whatsapp:channel:<jid>) invece della semantica delle sessioni DM.
• Il trasporto WhatsApp Web rispetta le variabili d'ambiente proxy standard sull'host del Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / varianti minuscole). Preferisci la configurazione proxy a livello host rispetto alle impostazioni proxy WhatsApp specifiche del canale.
• Quando messages.removeAckAfterReply è abilitato, OpenClaw cancella la reazione di ack WhatsApp dopo la consegna di una risposta visibile.

# Hook dei plugin e privacy

I messaggi WhatsApp in ingresso possono contenere contenuto di messaggi personali, numeri di telefono, identificatori di gruppo, nomi dei mittenti e campi di correlazione della sessione. Per questo motivo, WhatsApp non trasmette i payload degli hook message_received in ingresso ai plugin a meno che tu non faccia opt-in esplicitamente:

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

Puoi limitare l'opt-in a un account:

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

Abilitalo solo per plugin di cui ti fidi per ricevere contenuto e identificatori dei messaggi WhatsApp in ingresso.

# Controllo degli accessi e attivazione

# Comportamento con numero personale e chat con sé stessi

Quando il numero personale collegato è presente anche in allowFrom, si attivano le salvaguardie WhatsApp per la chat con sé stessi:

• salta le conferme di lettura per i turni di chat con sé stessi
• ignora il comportamento di attivazione automatica mention-JID che altrimenti ti pingherebbe
• se messages.responsePrefix non è impostato, le risposte nella chat con sé stessi usano per impostazione predefinita [{identity.name}] o [openclaw]

# Normalizzazione dei messaggi e contesto

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

# Consegna, suddivisione in blocchi e media

# Citazione nelle risposte

WhatsApp supporta la citazione nativa nelle risposte, in cui le risposte in uscita citano visibilmente il messaggio in ingresso. Controllala con channels.whatsapp.replyToMode.

Il valore predefinito è "off". Gli override per account usano channels.whatsapp.accounts.<id>.replyToMode.

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

# Livello di reazione

channels.whatsapp.reactionLevel controlla quanto ampiamente l'agente usa le reazioni emoji su WhatsApp:

Predefinito: "minimal".

Gli override per account usano channels.whatsapp.accounts.<id>.reactionLevel.

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

# Reazioni di conferma

WhatsApp supporta reazioni di conferma immediate alla ricezione in ingresso tramite channels.whatsapp.ackReaction. Le reazioni di conferma sono controllate da reactionLevel: vengono soppresse quando reactionLevel è "off".

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

Note sul comportamento:

• inviate immediatamente dopo l'accettazione del messaggio in ingresso (prima della risposta)
• gli errori vengono registrati ma non bloccano la normale consegna della risposta
• la modalità gruppo mentions reagisce ai turni attivati da menzioni; l'attivazione del gruppo always permette di saltare questo controllo
• WhatsApp usa channels.whatsapp.ackReaction (il valore legacy messages.ackReaction non viene usato qui)

# Multi-account e credenziali

# Strumenti, azioni e scritture di configurazione

• Il supporto agli strumenti dell'agente include l'azione di reazione WhatsApp (react).
• Gate delle azioni:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Le scritture di configurazione avviate dal canale sono abilitate per impostazione predefinita (disabilita tramite channels.whatsapp.configWrites=false).

# Risoluzione dei problemi

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# Prompt di sistema

WhatsApp supporta prompt di sistema in stile Telegram per gruppi e chat dirette tramite le mappe groups e direct.

Gerarchia di risoluzione per i messaggi di gruppo:

La mappa groups effettiva viene determinata per prima: se l'account definisce i propri groups, sostituisce completamente la mappa groups radice (nessun deep merge). La ricerca del prompt viene quindi eseguita sulla singola mappa risultante:

1. Prompt di sistema specifico del gruppo (groups["<groupId>"].systemPrompt): usato quando la voce del gruppo specifico esiste nella mappa e la sua chiave systemPrompt è definita. Se systemPrompt è una stringa vuota (""), il carattere jolly viene soppresso e non viene applicato alcun prompt di sistema.
2. Prompt di sistema jolly del gruppo (groups["*"].systemPrompt): usato quando la voce del gruppo specifico è del tutto assente dalla mappa oppure quando esiste ma non definisce alcuna chiave systemPrompt.

Gerarchia di risoluzione per i messaggi diretti:

La mappa direct effettiva viene determinata per prima: se l'account definisce la propria direct, sostituisce completamente la mappa direct radice (nessun deep merge). La ricerca del prompt viene quindi eseguita sulla singola mappa risultante:

1. Prompt di sistema specifico per chat diretta (direct["<peerId>"].systemPrompt): usato quando la voce del peer specifico esiste nella mappa e la sua chiave systemPrompt è definita. Se systemPrompt è una stringa vuota (""), il jolly viene soppresso e non viene applicato alcun prompt di sistema.
2. Prompt di sistema jolly per chat diretta (direct["*"].systemPrompt): usato quando la voce del peer specifico è completamente assente dalla mappa, oppure quando esiste ma non definisce alcuna chiave systemPrompt.

Differenza rispetto al comportamento multi-account di Telegram: In Telegram, groups a livello radice viene intenzionalmente soppresso per tutti gli account in una configurazione con più account, anche per gli account che non definiscono propri groups, per impedire a un bot di ricevere messaggi di gruppo per gruppi a cui non appartiene. WhatsApp non applica questa protezione: groups a livello radice e direct a livello radice vengono sempre ereditati dagli account che non definiscono override a livello di account, indipendentemente da quanti account siano configurati. In una configurazione WhatsApp con più account, se vuoi prompt di gruppo o diretti per account, definisci esplicitamente la mappa completa sotto ciascun account invece di affidarti ai valori predefiniti a livello radice.

Comportamento importante:

• channels.whatsapp.groups è sia una mappa di configurazione per gruppo sia la allowlist dei gruppi a livello di chat. A livello radice o di account, groups["*"] significa "tutti i gruppi sono ammessi" per quell'ambito.
• Aggiungi un systemPrompt di gruppo jolly solo quando vuoi già che quell'ambito ammetta tutti i gruppi. Se vuoi comunque che sia idoneo solo un insieme fisso di ID gruppo, non usare groups["*"] per il valore predefinito del prompt. Ripeti invece il prompt su ogni voce di gruppo esplicitamente inclusa nella allowlist.
• L'ammissione del gruppo e l'autorizzazione del mittente sono controlli separati. groups["*"] amplia l'insieme dei gruppi che possono raggiungere la gestione dei gruppi, ma da solo non autorizza ogni mittente in quei gruppi. L'accesso del mittente è comunque controllato separatamente da channels.whatsapp.groupPolicy e channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct non ha lo stesso effetto collaterale per i DM. direct["*"] fornisce solo una configurazione predefinita per le chat dirette dopo che un DM è già stato ammesso da dmPolicy più allowFrom o dalle regole dell'archivio di associazione.

Esempio:

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "[email protected]": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

# Puntatori di riferimento per la configurazione

Riferimento principale:

• Riferimento della configurazione - WhatsApp

Campi WhatsApp ad alto segnale:

• accesso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• recapito: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• più account: accounts.<id>.enabled, accounts.<id>.authDir, override a livello di account
• operazioni: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• comportamento della sessione: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompt: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

# Correlati

• Associazione
• Gruppi
• Sicurezza
• Instradamento dei canali
• Instradamento multi-agente
• Risoluzione dei problemi