Plateformes de messagerie

WhatsApp

Statut : prêt pour la production via WhatsApp Web (Baileys). La passerelle possède la/les session(s) liée(s).

Appairage

La politique DM par défaut est l'appairage pour les expéditeurs inconnus.

Dépannage des canaux

Diagnostics inter-canaux et procédures de réparation.

Configuration de la passerelle

Modèles et exemples complets de configuration des canaux.

Configuration rapide

Étape 1 : Configurer la politique d'accès WhatsApp

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

Étape 2 : Lier WhatsApp (QR)

openclaw channels login --channel whatsapp

Pour un compte spécifique :

openclaw channels login --channel whatsapp --account work

Étape 3 : Démarrer la passerelle

openclaw gateway

Étape 4 : Approuver la première demande d'appairage (si mode appairage)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Les demandes d'appairage expirent après 1 heure. Les demandes en attente sont limitées à 3 par canal.

ℹ️ OpenClaw recommande d'exécuter WhatsApp sur un numéro séparé lorsque c'est possible. (Les métadonnées du canal et le flux d'intégration sont optimisés pour cette configuration, mais les configurations avec numéro personnel sont également prises en charge.)

Modèles de déploiement

Modèle d'exécution

  • La passerelle possède le socket WhatsApp et la boucle de reconnexion.
  • Les envois sortants nécessitent un écouteur WhatsApp actif pour le compte cible.
  • Les chats de statut et de diffusion sont ignorés (@status, @broadcast).
  • Les conversations directes utilisent les règles de session DM (session.dmScope ; par défaut main regroupe les DM vers la session principale de l'agent).
  • Les sessions de groupe sont isolées (agent:<agentId>:whatsapp:group:<jid>).

Contrôle d'accès et activation

channels.whatsapp.dmPolicy contrôle l'accès aux conversations directes :

  • pairing (par défaut)
  • allowlist
  • open (nécessite que allowFrom inclue "*")
  • disabled

allowFrom accepte les numéros au format E.164 (normalisés en interne). Surcharge multi-compte : channels.whatsapp.accounts.<id>.dmPolicy (et allowFrom) prennent la priorité sur les valeurs par défaut au niveau du canal pour ce compte. Détails du comportement d'exécution :

  • les appairages sont persistés dans le magasin d'autorisation du canal et fusionnés avec allowFrom configuré
  • si aucune liste d'autorisation n'est configurée, le numéro personnel lié est autorisé par défaut
  • les DM sortants fromMe ne sont jamais auto-appairés

Comportement avec numéro personnel et auto-conversation

Lorsque le numéro personnel lié est également présent dans allowFrom, les protections d'auto-conversation WhatsApp s'activent :

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

Normalisation des messages et contexte

Livraison, fragmentation et médias

Réactions d'accusé de réception

WhatsApp prend en charge les réactions d'accusé de réception immédiates sur réception entrante via channels.whatsapp.ackReaction.

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

Notes de comportement :

  • envoyé immédiatement après l'acceptation de l'entrée (avant la réponse)
  • les échecs sont journalisés mais ne bloquent pas la livraison normale de la réponse
  • le mode groupe mentions réagit sur les tours déclenchés par 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)

Multi-comptes et identifiants

Outils, actions et écritures de configuration

  • La prise en charge des outils d'agent inclut l'action de réaction WhatsApp (react).
  • Portes 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ésactiver via channels.whatsapp.configWrites=false).

Dépannage

Pointeurs de référence de configuration

Référence principale :

Champs WhatsApp à fort signal :

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

Liens connexes

TwitchZalo