WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

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é

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

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

​

Contrôle d’accès et activation

​

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

• 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

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

​

Niveau de réaction

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

​

Réactions d’accusé de réception

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

• 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

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.

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.

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

{
  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.
            "120363406415684625@g.us": {
              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 de configuration - WhatsApp

• 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