WhatsApp

ZeroClaw prend en charge deux backends WhatsApp au sein de la même famille de configuration channels.whatsapp :

Ne configurez pas les deux sélecteurs dans le même canal, sauf si vous souhaitez intentionnellement que le mode Cloud API l’emporte pour des raisons de rétrocompatibilité.

Qui peut parler à l’agent

Les expéditeurs entrants sont filtrés par rapport au peer set résolu pour l’agent lié, issu de la configuration peer_groups à laquelle l’agent appartient. La correspondance supprime le @ initial et est insensible à la casse par rapport à l’identifiant d’expéditeur natif du canal. Un ensemble vide refuse tout le monde ; un ensemble contenant "*" accepte n’importe qui ; sinon, seuls les pairs externes listés (et les agents pairs) sont acceptés. Ceci est distinct de l’appairage de la passerelle (gateway.require_pairing), qui authentifie les clients HTTP/WebSocket, et non les expéditeurs des canaux de discussion.

Un groupe de pairs pour whatsapp définit channel à whatsapp, liste les expéditeurs autorisés dans external_peers (pour whatsapp, un identifiant de téléphone (Cloud API) ou la partie utilisateur du JID (mode Web) ; ["*"] accepte tout le monde), nomme éventuellement des agents pairs pour la répartition inter-agents, une liste de blocage ignore, et une output_modality (mirror, voice ou text). Consultez Peer Groups pour la référence des champs.

Où définir ce paramètre :

Mode API Cloud

Le mode Cloud API est l’intégration à la Meta Business Platform. Il nécessite un compte Meta Business, une application WhatsApp Business, un identifiant de numéro de téléphone, un jeton de vérification, un jeton d’accès et un secret d’application. C’est le mode approprié pour les déploiements professionnels qui reçoivent des messages via les webhooks Meta.

Les webhooks entrants sont vérifiés par signature avec app_secret, et cette vérification est obligatoire. Si aucun secret d’application n’est configuré, la passerelle ne peut pas vérifier une requête ; elle répond donc 401 et ne traite rien. Définissez app_secret avant de configurer Meta pour pointer vers l’URL de rappel.

La passerelle doit être accessible par Meta pour les webhooks entrants. Configurez un tunnel sous la section de niveau supérieur [tunnel] (tunnel_provider et les blocs de fournisseur associés, voir la référence de configuration), ou placez la passerelle derrière votre propre proxy inverse lors du développement en local.

Faites pointer l’URL de rappel de Meta vers l’alias de l’instance [channels.whatsapp.<alias>] censée la recevoir : GET/POST https://<your-public-url>/whatsapp/<alias> (par ex. [channels.whatsapp.work] → /whatsapp/work). Ce routage par alias (#6312) permet de faire fonctionner plusieurs numéros WhatsApp côte à côte. Le chemin nu /whatsapp fonctionne toujours mais est déprécié : il se résout vers le premier alias dans l’ordre lexicographique (déterministe d’un redémarrage à l’autre) et définit un en-tête de réponse X-Zeroclaw-Deprecation. Un alias inconnu renvoie 404. Les déploiements à instance unique ne nécessitent aucune modification.

Mode Web

Le mode WhatsApp Web associe un compte WhatsApp standard via le backend Web optionnel. Il ne nécessite pas de compte Meta Business. Il nécessite en revanche une build de ZeroClaw avec la fonctionnalité whatsapp-web activée et un chemin de base de données de session persistante.

Au premier démarrage, le backend Web appaire le compte via un lien par QR ou par code d’appairage (pair_phone initialise le lien par code d’appairage ; laissez-le non défini pour le QR). Conservez session_path sur un stockage persistant ; sa suppression force un nouveau lien d’appareil. Liez le canal à un agent via la liste channels de cet agent.

push_name définit le nom d’affichage que voient les destinataires ; laissez-le non défini et le compte conserve le nom avec lequel le téléphone a été enregistré. Il est appliqué lors de la connexion, uniquement lorsqu’il diffère du nom déjà porté par l’appareil lié, et l’échec de son application est consigné sans interrompre le canal. Le mode Cloud API l’ignore ; dans ce mode, le nom d’affichage provient du profil Meta Business.

L’option partagée interrupt_on_new_message s’applique à la fois au mode Cloud API et au mode Web. Lorsqu’elle est activée, un nouveau message WhatsApp provenant du même expéditeur/de la même conversation annule la réponse en cours.

Comportement personnel et professionnel

Pour le mode Web, dm_policy et group_policy s’appliquent dans les deux modes. self_chat_mode est réservé à l’usage personnel :

self_chat_mode reste réservé à l’usage personnel, car la fonctionnalité de discussion avec soi-même est, par conception, limitée à la branche personnelle. mode sélectionne l’orientation de la politique de ZeroClaw, et non un type de compte WhatsApp : les deux modes pilotent la même session d’appareil lié.

La garde fromMe reste également dans la branche personnelle, mais pas parce que le mode professionnel n’a pas d’équivalent. Le mode professionnel reste une session d’appareil lié à WhatsApp Web, et WhatsApp répercute les propres messages sortants de l’opérateur sur les appareils liés sous la forme fromMe, quel que soit le mode. Le compte lié est enregistré comme pair autorisé, si bien qu’en mode professionnel cette réplique peut satisfaire la liste d’autorisation et atteindre le dispatch, ce qui correspond au scénario que #6353 a corrigé pour le mode personnel. Ce comportement est antérieur à cette modification et n’est pas introduit ici ; il est signalé plutôt qu’écarté par une simple assertion, et sa correction fait l’objet d’un suivi séparé.

Note de compatibilité pour mode = "business"

Le mode professionnel acceptait auparavant dm_policy et group_policy, sans jamais consulter l’un ou l’autre ; un canal indiqué comme restrictif répondait donc à chaque message reçu. Les deux clés sont désormais prises en compte en mode professionnel.

dm_policy prend par défaut la valeur allowlist, donc un déploiement en mode entreprise qui reposait sur le comportement permissif précédent doit choisir l’une des options suivantes :

• Continuez à répondre à tout le monde - définissez dm_policy = "all" et group_policy = "all" explicitement.
• Conservez la restriction - laissez les valeurs par défaut et assurez-vous que les expéditeurs que vous souhaitez desservir sont accessibles via le groupe de pairs du canal, par l’intermédiaire de [peer_groups.<name>].external_peers.

N’attendez pas que config validate vous l’indique. Avec mode = "business", il signale que self_chat_mode est inerte et ne dit rien de dm_policy ni de group_policy, précisément parce que ces deux paramètres sont désormais actifs plutôt qu’inerte. Les clés dont le comportement a réellement changé pour vous sont donc celles que le validateur ne mentionnera pas. Lisez cette section avant la mise à niveau ; c’est le seul avis reçu par un déploiement en mode business.

passive_group_context = true est opt-in et s’applique uniquement aux discussions de groupe WhatsApp Web. Les messages de groupe non adressés autorisés sont stockés dans l’historique de conversation limité à la room sans démarrer un tour d’agent, envoyer des réactions, télécharger des médias ou appeler le modèle. Les messages adressés ultérieurs dans le même groupe peuvent utiliser ce contexte passif.

Restreindre quels groupes (allowed_groups)

allowed_groups (mode Web) restreint le bot à un ensemble nommé de discussions de groupe selon leur JID. Ce paramètre est indépendant de mode - il s’applique aussi bien au mode professionnel qu’au mode personnel et s’exécute avant la politique relative au type de discussion. Une liste vide n’est pas une autorisation : sa signification est déterminée par group_policy. Avec allowlist (la valeur par défaut) ou ignore, une liste vide n’autorise aucun groupe, tandis qu’avec all, elle les autorise tous. Une liste qui autorise tous les groupes ne peut pas être distinguée d’une liste qui n’a été configurée par personne ; l’accès ouvert aux groupes doit donc être demandé explicitement. Une liste non vide exclut tout message de groupe dont le JID de discussion ne correspond à aucune entrée et continue à le faire avec toutes les politiques, y compris all. Ainsi, all élargit le comportement par défaut d’une liste vide au lieu de remplacer une liste explicite. Les messages directs contournent toujours ce filtre.

Chaque entrée correspond soit au JID complet du groupe (123456789012345@g.us), soit à la partie utilisateur du JID — la partie avant @ (123456789012345) — comparée exactement, et non comme un préfixe de chaîne (ce qui signifie que 123 accepte 123@g.us mais jamais 123999@g.us). Cela vérifie l’identité du groupe, ce que ne font ni group_policy (type de chat) ni la liste d’autorisation des expéditeurs (expéditeur).

[channels.whatsapp.myaccount]
enabled = true
session_path = "/var/lib/zeroclaw/wa.db"
# N'opérer que dans ces deux groupes ; tous les autres groupes sont ignorés.
allowed_groups = ["120363012345678901@g.us", "120363098765432109"]

Approbation de l’outil via le chat (approval_timeout_secs)

Lorsqu’un outil nécessite une approbation (il figure dans always_ask ou le profil de risque ne l’approuve pas automatiquement), l’agent publie la demande dans le chat d’où provient le message et attend une réponse. Répondez avec le jeton indiqué dans l’invite :

a1b2c3 yes
a1b2c3 no
a1b2c3 always

approval_timeout_secs limite cette attente. La valeur par défaut est de 300 secondes, et 0 refuse immédiatement au lieu de désactiver l’approbation ; zéro permet donc de refuser chaque outil soumis à approbation, et non d’attendre indéfiniment. À l’expiration du délai, la requête est refusée et le jeton est supprimé ; une réponse tardive ne peut donc pas approuver un appel que plus personne n’attend.

Qui peut répondre. Le jeton est un identifiant de corrélation, pas un mot de passe : il est transmis en clair dans le chat, donc, dans un groupe, chaque membre peut le lire.

Les deux modes diffèrent, et cette différence constitue une frontière de sécurité plutôt qu’un détail d’implémentation.

En mode Web, une réponse n’est prise en compte que si elle provient du même chat que celui dans lequel l’invite a été publiée et d’un pair auprès duquel cet alias est autorisé à recevoir des instructions. Toute réponse qui échoue à l’une ou l’autre de ces vérifications est journalisée et ignorée, et la demande reste ouverte afin que l’opérateur puisse toujours y répondre. Dans un groupe, l’invite le précise, car sinon il est impossible de savoir pourquoi la réponse d’un autre participant n’a rien fait.

Les pairs autorisés sont ceux que le résolveur canonique renvoie pour cet alias, c’est-à-dire le groupe de pairs dont le channel pointe vers celui-ci :

[peer_groups.whatsapp_default]
channel = "whatsapp.personal"   # this alias only; bare "whatsapp" covers every alias
external_peers = ["+15550100"]

Il n’y a aucun champ allowed_numbers à définir. C’était la forme utilisée en v2, et la migration l’intègre à un groupe de pairs comme celui ci-dessus ; ainsi, une configuration v2 continue de fonctionner et une configuration v3 n’a nulle part où placer l’ancienne clé.

Voir Groupes de pairs pour consulter la liste complète des champs et la structure d’identifiant utilisée par chaque canal pour effectuer la correspondance.

En mode Cloud API, aucun des deux contrôles n’est appliqué. Son entrée en attente est un simple répondant indexé par le jeton, sans conversation ni identité enregistrée à ses côtés ; le webhook considère donc la possession du jeton comme une autorisation. Dans un groupe, cela signifie que tout membre capable de lire l’invite peut y répondre, y compris depuis une autre conversation. Tant que cette voie n’est pas renforcée, une approbation en mode Cloud prouve seulement que quelqu’un détenait le jeton, et rien de plus. Elle n’authentifie ni la conversation ni le répondant ; préférez donc le mode Web lorsque l’un ou l’autre importe.

Surfaces de configuration

zeroclaw config set channels.whatsapp.<alias>.access_token    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__whatsapp__<alias>__access_token=

zeroclaw config set channels.whatsapp.<alias>.allowed_groups <value>

export ZEROCLAW_channels__whatsapp__<alias>__allowed_groups=

zeroclaw config set channels.whatsapp.<alias>.app_secret    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__whatsapp__<alias>__app_secret=

zeroclaw config set channels.whatsapp.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__whatsapp__<alias>__approval_timeout_secs=

zeroclaw config set channels.whatsapp.<alias>.dm_mention_patterns <value>

export ZEROCLAW_channels__whatsapp__<alias>__dm_mention_patterns=

zeroclaw config set channels.whatsapp.<alias>.dm_policy <value>

export ZEROCLAW_channels__whatsapp__<alias>__dm_policy=

zeroclaw config set channels.whatsapp.<alias>.excluded_tools <value>

export ZEROCLAW_channels__whatsapp__<alias>__excluded_tools=

zeroclaw config set channels.whatsapp.<alias>.group_mention_patterns <value>

export ZEROCLAW_channels__whatsapp__<alias>__group_mention_patterns=

zeroclaw config set channels.whatsapp.<alias>.group_policy <value>

export ZEROCLAW_channels__whatsapp__<alias>__group_policy=

zeroclaw config set channels.whatsapp.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__whatsapp__<alias>__interrupt_on_new_message=

zeroclaw config set channels.whatsapp.<alias>.mention_only <value>

export ZEROCLAW_channels__whatsapp__<alias>__mention_only=

zeroclaw config set channels.whatsapp.<alias>.mode <value>

export ZEROCLAW_channels__whatsapp__<alias>__mode=

zeroclaw config set channels.whatsapp.<alias>.pair_code <value>

export ZEROCLAW_channels__whatsapp__<alias>__pair_code=

zeroclaw config set channels.whatsapp.<alias>.pair_phone <value>

export ZEROCLAW_channels__whatsapp__<alias>__pair_phone=

zeroclaw config set channels.whatsapp.<alias>.passive_group_context <value>

export ZEROCLAW_channels__whatsapp__<alias>__passive_group_context=

zeroclaw config set channels.whatsapp.<alias>.phone_number_id <value>

export ZEROCLAW_channels__whatsapp__<alias>__phone_number_id=

zeroclaw config set channels.whatsapp.<alias>.proxy_url <value>

export ZEROCLAW_channels__whatsapp__<alias>__proxy_url=

zeroclaw config set channels.whatsapp.<alias>.push_name <value>

export ZEROCLAW_channels__whatsapp__<alias>__push_name=

zeroclaw config set channels.whatsapp.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__whatsapp__<alias>__reply_min_interval_secs=

zeroclaw config set channels.whatsapp.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__whatsapp__<alias>__reply_queue_depth_max=

zeroclaw config set channels.whatsapp.<alias>.self_chat_mode <value>

export ZEROCLAW_channels__whatsapp__<alias>__self_chat_mode=

zeroclaw config set channels.whatsapp.<alias>.session_path <value>

export ZEROCLAW_channels__whatsapp__<alias>__session_path=

zeroclaw config set channels.whatsapp.<alias>.verify_token    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__whatsapp__<alias>__verify_token=

zeroclaw config set channels.whatsapp.<alias>.ws_url <value>

export ZEROCLAW_channels__whatsapp__<alias>__ws_url=

channels.whatsapp.<alias>.access_token est un secret. Stocké chiffré, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent à l’écriture :

zeroclaw config set channels.whatsapp.<alias>.access_token    # demande une saisie masquée, stocke de manière chiffrée

Il en va de même pour verify_token et app_secret (Cloud API).

Démarrer et vérifier

Après avoir configuré un mode, démarrez le channel runner :

zeroclaw channel start

Utilisez zeroclaw channel doctor pour une première vérification. Pour le mode Web, confirmez également que le binaire a été compilé avec whatsapp-web ; pour le mode Cloud API, confirmez que le tunnel webhook et le verify token Meta concordent.