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.

​

Instalación (bajo demanda)

• La incorporación (openclaw onboard) y openclaw channels add --channel whatsapp solicitan instalar el Plugin de WhatsApp la primera vez que lo seleccionas.
• openclaw channels login --channel whatsapp también ofrece el flujo de instalación cuando el Plugin aún no está presente.
• Canal de desarrollo + checkout de git: usa de forma predeterminada la ruta local del Plugin.
• Stable/Beta: usa el paquete npm @openclaw/whatsapp en la etiqueta de versión oficial actual.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

Configuración rápida

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

​

Patrones de despliegue

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

​

Modelo de tiempo de ejecución

• Gateway gestiona el socket de WhatsApp y el bucle de reconexión.
• El vigilante de reconexión usa la actividad de transporte de WhatsApp Web, no solo el volumen de mensajes entrantes de la aplicación, por lo que una sesión silenciosa de dispositivo vinculado no se reinicia solo porque nadie haya enviado un mensaje recientemente. Un límite más largo de silencio de la aplicación sigue forzando una reconexión si los frames de transporte continúan llegando pero no se procesa ningún mensaje de aplicación durante la ventana del vigilante; después de una reconexión transitoria para una sesión activa recientemente, esa comprobación de silencio de la aplicación usa el tiempo de espera normal de mensajes para la primera ventana de recuperación.
• Los tiempos del socket de Baileys son explícitos bajo web.whatsapp.*: keepAliveIntervalMs controla los pings de aplicación de WhatsApp Web, connectTimeoutMs controla el tiempo de espera del handshake de apertura y defaultQueryTimeoutMs controla los tiempos de espera de consultas de Baileys.
• Los envíos salientes requieren un listener de WhatsApp activo para la cuenta de destino.
• Los envíos a grupos adjuntan metadatos nativos de mención para tokens @+<digits> y @<digits> en texto y pies de medios cuando el token coincide con los metadatos actuales de participantes de WhatsApp, incluidos grupos respaldados por LID.
• Los chats de estado y difusión se ignoran (@status, @broadcast).
• El vigilante de reconexión sigue la actividad de transporte de WhatsApp Web, no solo el volumen de mensajes entrantes de la aplicación: las sesiones silenciosas de dispositivo vinculado permanecen activas mientras continúen los frames de transporte, pero un bloqueo del transporte fuerza una reconexión mucho antes de la ruta posterior de desconexión remota.
• Los chats directos usan reglas de sesión de DM (session.dmScope; el valor predeterminado main colapsa los DM en la sesión principal del agente).
• Las sesiones de grupo están aisladas (agent:<agentId>:whatsapp:group:<jid>).
• Los canales/newsletters de WhatsApp pueden ser destinos salientes explícitos con su JID nativo @newsletter. Los envíos salientes a newsletters usan metadatos de sesión de canal (agent:<agentId>:whatsapp:channel:<jid>) en lugar de semántica de sesión de DM.
• El transporte de WhatsApp Web respeta las variables de entorno de proxy estándar en el host de Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / variantes en minúsculas). Prefiere la configuración de proxy a nivel de host frente a ajustes de proxy de WhatsApp específicos del canal.
• Cuando messages.removeAckAfterReply está habilitado, OpenClaw borra la reacción de acuse de WhatsApp después de que se entrega una respuesta visible.

​

Hooks de Plugin y privacidad

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

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

​

Control de acceso y activación

​

Comportamiento con número personal y chat contigo mismo

• omitir confirmaciones de lectura para turnos de chat contigo mismo
• ignorar comportamiento de activación automática por mention-JID que de otro modo te haría ping a ti mismo
• si messages.responsePrefix no está definido, las respuestas de chat contigo mismo usan de forma predeterminada [{identity.name}] o [openclaw]

​

Normalización de mensajes y contexto

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

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

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

​

Entrega, fragmentación y multimedia

​

Citas en respuestas

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

​

Nivel de reacción

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

​

Reacciones de acuse

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

• se envían inmediatamente después de aceptar el mensaje entrante (antes de la respuesta)
• los fallos se registran, pero no bloquean la entrega normal de la respuesta
• el modo de grupo mentions reacciona en turnos activados por menciones; la activación de grupo always actúa como omisión para esta comprobación
• WhatsApp usa channels.whatsapp.ackReaction (el valor heredado messages.ackReaction no se usa aquí)

​

Varias cuentas y credenciales

​

Herramientas, acciones y escrituras de configuración

• La compatibilidad con herramientas del agente incluye la acción de reacción de WhatsApp (react).
• Controles de acciones:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Las escrituras de configuración iniciadas por el canal están activadas de forma predeterminada (desactivar mediante channels.whatsapp.configWrites=false).

​

Solución de problemas

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

​

Prompts del sistema

1. Prompt del sistema específico del grupo (groups["<groupId>"].systemPrompt): se usa cuando la entrada específica del grupo existe en el mapa y su clave systemPrompt está definida. Si systemPrompt es una cadena vacía (""), se suprime el comodín y no se aplica ningún prompt del sistema.
2. Prompt del sistema comodín de grupo (groups["*"].systemPrompt): se usa cuando la entrada específica del grupo está ausente por completo del mapa o cuando existe pero no define ninguna clave systemPrompt.

1. Prompt del sistema específico directo (direct["<peerId>"].systemPrompt): se usa cuando la entrada del par específico existe en el mapa y su clave systemPrompt está definida. Si systemPrompt es una cadena vacía (""), el comodín se suprime y no se aplica ningún prompt del sistema.
2. Prompt del sistema comodín directo (direct["*"].systemPrompt): se usa cuando la entrada del par específico está totalmente ausente del mapa, o cuando existe pero no define ninguna clave systemPrompt.

• channels.whatsapp.groups es tanto un mapa de configuración por grupo como la lista de permitidos de grupos a nivel de chat. En el ámbito raíz o de cuenta, groups["*"] significa “se admiten todos los grupos” para ese ámbito.
• Añade un systemPrompt de grupo comodín solo cuando ya quieras que ese ámbito admita todos los grupos. Si aún quieres que solo sea apto un conjunto fijo de IDs de grupo, no uses groups["*"] como valor predeterminado del prompt. En su lugar, repite el prompt en cada entrada de grupo incluida explícitamente en la lista de permitidos.
• La admisión de grupos y la autorización de remitentes son comprobaciones separadas. groups["*"] amplía el conjunto de grupos que pueden llegar al manejo de grupos, pero no autoriza por sí solo a todos los remitentes de esos grupos. El acceso de remitentes sigue controlándose por separado mediante channels.whatsapp.groupPolicy y channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct no tiene el mismo efecto secundario para los DM. direct["*"] solo proporciona una configuración predeterminada de chat directo después de que un DM ya haya sido admitido por dmPolicy más allowFrom o por reglas del almacén de emparejamiento.

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

​

Punteros de referencia de configuración

• Referencia de configuración - WhatsApp

• acceso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• entrega: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multicuenta: accounts.<id>.enabled, accounts.<id>.authDir, sobrescrituras a nivel de cuenta
• operaciones: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• comportamiento de sesión: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompts: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

​

Relacionado

• Emparejamiento
• Grupos
• Seguridad
• Enrutamiento de canales
• Enrutamiento multiagente
• Solución de problemas