WhatsApp

Statut : prêt pour la production via WhatsApp Web (Baileys). Gateway gère les sessions liées.

# Installation (à la demande)

• L’onboarding (openclaw onboard) et openclaw channels add --channel whatsapp proposent d’installer le Plugin WhatsApp la première fois que vous le sélectionnez.
• openclaw channels login --channel whatsapp propose aussi le flux d’installation lorsque le Plugin n’est pas encore présent.
• Canal de développement + dépôt git extrait : utilise par défaut le chemin du Plugin local.
• Stable/Bêta : utilise le package npm @openclaw/whatsapp sur l’étiquette de version officielle actuelle.

L’installation manuelle reste disponible :

openclaw plugins install @openclaw/whatsapp

Utilisez le package nu pour suivre l’étiquette de version officielle actuelle. Épinglez une version exacte uniquement lorsque vous avez besoin d’une installation reproductible.

Sous Windows, le Plugin WhatsApp a besoin de Git sur PATH pendant l’installation npm, car l’une de ses dépendances Baileys/libsignal est récupérée depuis une URL git. Installez Git for Windows, puis redémarrez le shell et relancez l’installation :

winget install --id Git.Git -e

Portable Git fonctionne aussi si son répertoire bin est sur PATH.

# Configuration rapide

{
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>

# Modèles de déploiement

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

# Modèle d’exécution

• Gateway gère la socket WhatsApp et la boucle de reconnexion.
• Le chien de garde de reconnexion utilise l’activité de transport WhatsApp Web, pas seulement le volume de messages applicatifs entrants, de sorte qu’une session d’appareil lié silencieuse n’est pas redémarrée uniquement parce que personne n’a envoyé de message récemment. Une limite plus longue de silence applicatif force tout de même une reconnexion si des trames de transport continuent d’arriver, mais qu’aucun message applicatif n’est traité pendant la fenêtre du chien de garde ; après une reconnexion transitoire pour une session récemment active, cette vérification de silence applicatif utilise le délai normal des messages pour la première fenêtre de récupération.
• Les temporisations de socket Baileys sont explicites sous web.whatsapp.* : keepAliveIntervalMs contrôle les pings applicatifs WhatsApp Web, connectTimeoutMs contrôle le délai d’expiration de la poignée de main d’ouverture, et defaultQueryTimeoutMs contrôle les délais d’expiration des requêtes Baileys.
• Les envois sortants nécessitent un écouteur WhatsApp actif pour le compte cible.
• Les envois de groupe joignent les métadonnées de mention natives pour les jetons @+<digits> et @<digits> dans le texte et les légendes de médias lorsque le jeton correspond aux métadonnées de participant WhatsApp actuelles, y compris les groupes adossés à LID.
• Les chats de statut et de diffusion sont ignorés (@status, @broadcast).
• Le chien de garde de reconnexion suit l’activité de transport WhatsApp Web, pas seulement le volume de messages applicatifs entrants : les sessions d’appareil lié silencieuses restent actives tant que les trames de transport continuent, mais un blocage du transport force une reconnexion bien avant le chemin ultérieur de déconnexion distante.
• Les chats directs utilisent les règles de session de MP (session.dmScope ; la valeur par défaut main regroupe les MP dans la session principale de l’agent).
• Les sessions de groupe sont isolées (agent:<agentId>:whatsapp:group:<jid>).
• Les canaux/newsletters WhatsApp peuvent être des cibles sortantes explicites avec leur JID natif @newsletter. Les envois sortants de newsletter utilisent les métadonnées de session de canal (agent:<agentId>:whatsapp:channel:<jid>) plutôt que la sémantique de session de MP.
• Le transport WhatsApp Web respecte les variables d’environnement de proxy standard sur l’hôte du Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / variantes en minuscules). Préférez la configuration de proxy au niveau de l’hôte aux paramètres de proxy WhatsApp propres au canal.
• Lorsque messages.removeAckAfterReply est activé, OpenClaw efface la réaction d’accusé de réception WhatsApp après la remise d’une réponse visible.

# Hooks de Plugin et confidentialité

Les messages entrants WhatsApp peuvent contenir le contenu de messages personnels, des numéros de téléphone, des identifiants de groupe, des noms d’expéditeurs et des champs de corrélation de session. Pour cette raison, WhatsApp ne diffuse pas les charges utiles de hook message_received entrant aux plugins sauf si vous l’activez explicitement :

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

Vous pouvez limiter l’activation à un seul compte :

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

Activez cette option uniquement pour les plugins auxquels vous faites confiance pour recevoir le contenu et les identifiants des messages WhatsApp entrants.

# Contrôle d’accès et activation

# Comportement avec numéro personnel et conversation avec soi-même

Lorsque le numéro propre lié est aussi présent dans allowFrom, les protections WhatsApp de conversation avec soi-même s’activent :

• ignorer les accusés de lecture pour les tours de conversation avec soi-même
• ignorer le comportement de déclenchement automatique par JID de mention qui vous notifierait autrement vous-même
• si messages.responsePrefix n’est pas défini, les réponses de conversation avec soi-même utilisent par défaut [{identity.name}] ou [openclaw]

# Normalisation des messages et contexte

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

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

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

# Livraison, découpage et médias

# Citation des réponses

WhatsApp prend en charge la citation native des réponses, où les réponses sortantes citent visiblement le message entrant. Contrôlez-la avec channels.whatsapp.replyToMode.

La valeur par défaut est "off". Les remplacements par compte utilisent channels.whatsapp.accounts.<id>.replyToMode.

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

# Niveau de réaction

channels.whatsapp.reactionLevel contrôle l’étendue de l’utilisation des réactions emoji par l’agent sur WhatsApp :

Par défaut : "minimal".

Les remplacements par compte utilisent channels.whatsapp.accounts.<id>.reactionLevel.

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

# Réactions d’accusé de réception

WhatsApp prend en charge les réactions d’accusé de réception immédiates à la réception entrante via channels.whatsapp.ackReaction. Les réactions d’accusé de réception sont contrôlées par reactionLevel — elles sont supprimées lorsque reactionLevel vaut "off".

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

Notes de comportement :

• envoyées immédiatement après l’acceptation du message entrant (avant la réponse)
• les échecs sont journalisés, mais ne bloquent pas la livraison normale de la réponse
• le mode de groupe mentions réagit sur les tours déclenchés par une mention ; l’activation de groupe always agit comme contournement pour cette vérification
• WhatsApp utilise channels.whatsapp.ackReaction (l’ancien messages.ackReaction n’est pas utilisé ici)

# Comptes multiples et identifiants

# Outils, actions et écritures de configuration

• La prise en charge des outils d’agent inclut l’action de réaction WhatsApp (react).
• Garde-fous d’action :
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Les écritures de configuration initiées par le canal sont activées par défaut (désactivation via channels.whatsapp.configWrites=false).

# Dépannage

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

# Prompts système

WhatsApp prend en charge les prompts système de style Telegram pour les groupes et les discussions directes via les cartes groups et direct.

Hiérarchie de résolution pour les messages de groupe :

La carte effective groups est déterminée en premier : si le compte définit ses propres groups, elle remplace entièrement la carte racine groups (pas de fusion profonde). La recherche de prompt s’exécute ensuite sur la carte unique résultante :

1. Prompt système propre au groupe (groups["<groupId>"].systemPrompt) : utilisé lorsque l’entrée du groupe spécifique existe dans la carte et que sa clé systemPrompt est définie. Si systemPrompt est une chaîne vide (""), le caractère générique est supprimé et aucun prompt système n’est appliqué.
2. Prompt système générique de groupe (groups["*"].systemPrompt) : utilisé lorsque l’entrée du groupe spécifique est entièrement absente de la carte, ou lorsqu’elle existe mais ne définit aucune clé systemPrompt.

Hiérarchie de résolution pour les messages directs :

La carte effective direct est déterminée en premier : si le compte définit sa propre carte direct, elle remplace entièrement la carte racine direct (pas de fusion profonde). La recherche de prompt s’exécute ensuite sur la carte unique résultante :

1. Invite système spécifique au direct (direct["<peerId>"].systemPrompt) : utilisée lorsque l’entrée du pair spécifique existe dans la map et que sa clé systemPrompt est définie. Si systemPrompt est une chaîne vide (""), le joker est supprimé et aucune invite système n’est appliquée.
2. Invite système joker du direct (direct["*"].systemPrompt) : utilisée lorsque l’entrée du pair spécifique est totalement absente de la map, ou lorsqu’elle existe mais ne définit aucune clé systemPrompt.

Différence avec le comportement multi-compte de Telegram : Dans Telegram, groups à la racine est volontairement supprimé pour tous les comptes dans une configuration multi-compte, même les comptes qui ne définissent pas leurs propres groups, afin d’empêcher un bot de recevoir des messages de groupes auxquels il n’appartient pas. WhatsApp n’applique pas cette protection : groups et direct à la racine sont toujours hérités par les comptes qui ne définissent aucun remplacement au niveau du compte, quel que soit le nombre de comptes configurés. Dans une configuration WhatsApp multi-compte, si vous voulez des invites de groupe ou de direct par compte, définissez explicitement la map complète sous chaque compte plutôt que de vous appuyer sur les valeurs par défaut au niveau racine.

Comportement important :

• channels.whatsapp.groups est à la fois une map de configuration par groupe et la liste d’autorisation des groupes au niveau du chat. À la racine comme au niveau du compte, groups["*"] signifie « tous les groupes sont admis » pour cette portée.
• N’ajoutez un systemPrompt de groupe joker que si vous voulez déjà que cette portée admette tous les groupes. Si vous voulez toujours que seul un ensemble fixe d’ID de groupes soit éligible, n’utilisez pas groups["*"] comme valeur par défaut de l’invite. Répétez plutôt l’invite sur chaque entrée de groupe explicitement autorisée.
• L’admission des groupes et l’autorisation des expéditeurs sont deux vérifications distinctes. groups["*"] élargit l’ensemble des groupes pouvant atteindre le traitement des groupes, mais n’autorise pas à lui seul chaque expéditeur dans ces groupes. L’accès des expéditeurs reste contrôlé séparément par channels.whatsapp.groupPolicy et channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct n’a pas le même effet secondaire pour les DM. direct["*"] fournit seulement une configuration de chat direct par défaut après qu’un DM a déjà été admis par dmPolicy plus allowFrom ou les règles du stockage d’appairage.

Exemple :

{
  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." },
          },
        },
      },
    },
  },
}

# Pointeurs de référence de configuration

Référence principale :

• Référence de configuration - WhatsApp

Champs WhatsApp à fort signal :

• accès : dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• livraison : textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multi-compte : accounts.<id>.enabled, accounts.<id>.authDir, remplacements au niveau du compte
• opérations : configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• comportement de session : session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• invites : groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

# Connexe

• Appairage
• Groupes
• Sécurité
• Routage des canaux
• Routage multi-agent
• Dépannage