Plataformas de mensajería

WhatsApp

Estado: listo para producción vía WhatsApp Web (Baileys). El gateway posee la(s) sesión(es) vinculada(s).

Vinculación (Pairing)

La política DM predeterminada es 'pairing' para remitentes desconocidos.

Solución de problemas del canal

Diagnósticos entre canales y guías de reparación.

Configuración del gateway

Patrones y ejemplos completos de configuración de canales.

Configuración rápida

Paso 1: Configurar la política de acceso de WhatsApp

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

Paso 2: Vincular WhatsApp (QR)

openclaw channels login --channel whatsapp

Para una cuenta específica:

openclaw channels login --channel whatsapp --account work

Paso 3: Iniciar el gateway

openclaw gateway

Paso 4: Aprobar la primera solicitud de vinculación (si se usa el modo pairing)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Las solicitudes de vinculación expiran después de 1 hora. Las solicitudes pendientes están limitadas a 3 por canal.

ℹ️ OpenClaw recomienda ejecutar WhatsApp en un número separado cuando sea posible. (Los metadatos del canal y el flujo de incorporación están optimizados para esa configuración, pero también se admiten configuraciones con número personal.)

Patrones de despliegue

Modelo de tiempo de ejecución

  • El gateway posee el socket de WhatsApp y el bucle de reconexión.
  • Los envíos salientes requieren un listener de WhatsApp activo para la cuenta objetivo.
  • Los chats de estado y difusión se ignoran (@status, @broadcast).
  • Los chats directos usan reglas de sesión DM (session.dmScope; por defecto main colapsa los DMs a la sesión principal del agente).
  • Las sesiones de grupo están aisladas (agent:<agentId>:whatsapp:group:<jid>).

Control de acceso y activación

channels.whatsapp.dmPolicy controla el acceso a chats directos:

  • pairing (predeterminado)
  • allowlist
  • open (requiere que allowFrom incluya "*")
  • disabled

allowFrom acepta números en formato E.164 (normalizados internamente).Anulación multi-cuenta: channels.whatsapp.accounts.<id>.dmPolicy (y allowFrom) tienen prioridad sobre los valores predeterminados a nivel de canal para esa cuenta.Detalles del comportamiento en tiempo de ejecución:

  • las vinculaciones se persisten en el almacén de permitidos del canal y se fusionan con allowFrom configurado
  • si no se configura ninguna lista de permitidos, el número propio vinculado se permite por defecto
  • los DMs salientes fromMe nunca se vinculan automáticamente

Comportamiento de número personal y chat propio

Cuando el número propio vinculado también está presente en allowFrom, se activan las salvaguardas de chat propio de WhatsApp:

  • omitir recibos de lectura para turnos de chat propio
  • ignorar el comportamiento de activación automática por mención-JID que de otro modo se enviaría a ti mismo
  • si messages.responsePrefix no está configurado, las respuestas de chat propio usan por defecto [{identity.name}] o [openclaw]

Normalización de mensajes y contexto

Entrega, fragmentación y medios

Reacciones de acuse de recibo

WhatsApp admite reacciones de acuse de recibo inmediatas en la recepción entrante mediante channels.whatsapp.ackReaction.

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

Notas de comportamiento:

  • se envía inmediatamente después de aceptar la entrada (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 mención; la activación de grupo always actúa como omisión para esta verificación
  • WhatsApp usa channels.whatsapp.ackReaction (el legado messages.ackReaction no se usa aquí)

Multi-cuenta y credenciales

Herramientas, acciones y escrituras de configuración

  • El soporte de herramientas del agente incluye la acción de reacción de WhatsApp (react).
  • Compuertas de acción:
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • Las escrituras de configuración iniciadas por el canal están habilitadas por defecto (desactivar mediante channels.whatsapp.configWrites=false).

Solución de problemas

Puntos de referencia de configuración

Referencia principal:

Campos de WhatsApp de alta señal:

  • acceso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
  • entrega: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
  • multi-cuenta: accounts.<id>.enabled, accounts.<id>.authDir, anulaciones a nivel de cuenta
  • operaciones: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
  • comportamiento de sesión: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

Relacionado

TwitchZalo