WhatsApp

ZeroClaw admite dos backends de WhatsApp en la misma familia de configuración channels.whatsapp:

No configure ambos selectores en el mismo canal a menos que quiera intencionadamente que el modo Cloud API prevalezca por compatibilidad con versiones anteriores.

Quién puede hablar con el agente

Los remitentes entrantes se filtran contra el conjunto de pares resuelto para el agente vinculado, obtenido de la configuración peer_groups a la que pertenece el agente. La coincidencia elimina el @ inicial y no distingue mayúsculas de minúsculas frente al identificador nativo de remitente del canal. Un conjunto vacío deniega a todos; un conjunto que contiene "*" acepta a cualquiera; en caso contrario, solo se aceptan los pares externos listados (y los agentes pares). Esto es independiente del emparejamiento de la puerta de enlace (gateway.require_pairing), que autentica clientes HTTP/WebSocket, no remitentes de canales de chat.

Un grupo de pares para whatsapp establece channel en whatsapp, enumera los remitentes permitidos en external_peers (para whatsapp, un identificador de teléfono (Cloud API) o la parte de usuario del JID (modo Web); ["*"] acepta a cualquiera), opcionalmente nombra agents pares para el despacho entre agentes, una lista de bloqueo ignore y un output_modality (mirror, voice o text). Consulta Peer Groups para la referencia de campos.

Dónde configurar esto:

Modo Cloud API

El modo Cloud API es la integración con Meta Business Platform. Requiere una cuenta de Meta Business, una aplicación de WhatsApp Business, un ID de número de teléfono, un token de verificación, un token de acceso y un secreto de aplicación. Es el modo adecuado para implementaciones empresariales que reciben mensajes a través de webhooks de Meta.

Los webhooks entrantes se verifican mediante firma con app_secret, y la verificación es obligatoria. Si no se configura ningún secreto de aplicación, la puerta de enlace no puede verificar una solicitud, por lo que responde con 401 y no procesa nada. Establece app_secret antes de configurar en Meta la URL de callback.

El gateway debe ser accesible por Meta para los webhooks entrantes. Configura un túnel en la sección de nivel superior [tunnel] (tunnel_provider y los bloques de proveedor relacionados, consulta la referencia de configuración), o coloca tu propio proxy inverso delante del gateway cuando desarrolles localmente.

Apunta la Callback URL de Meta al alias de la instancia [channels.whatsapp.<alias>] que debe recibirla: GET/POST https://<your-public-url>/whatsapp/<alias> (p. ej. [channels.whatsapp.work] → /whatsapp/work). Este enrutamiento por alias (#6312) permite ejecutar varios números de WhatsApp en paralelo. La ruta simple /whatsapp sigue funcionando, pero está obsoleta: se resuelve al primer alias en orden lexicográfico (determinista entre reinicios) y establece un encabezado de respuesta X-Zeroclaw-Deprecation. Un alias desconocido devuelve 404. Los despliegues de instancia única no requieren ningún cambio.

Modo web

El modo WhatsApp Web vincula una cuenta normal de WhatsApp a través del backend opcional Web. No necesita una cuenta de Meta Business. Sí necesita una compilación de ZeroClaw con la característica whatsapp-web habilitada y una ruta de base de datos de sesión persistente.

Al iniciarse por primera vez, el backend Web empareja la cuenta mediante vinculación por QR o por código de emparejamiento (pair_phone inicia la vinculación por código de emparejamiento; déjelo sin definir para usar QR). Mantenga session_path en almacenamiento persistente; eliminarlo fuerza una nueva vinculación del dispositivo. Vincule el canal a un agente a través de la lista channels de ese agente.

push_name establece el nombre para mostrar que ven los destinatarios; si no se establece, la cuenta conserva el nombre con el que se registró el teléfono. Se aplica al conectarse, solo cuando difiere del nombre que ya tiene el dispositivo vinculado, y si no se puede aplicar, se registra el error sin detener el canal. El modo Cloud API lo ignora; en ese caso, el nombre para mostrar procede del perfil de Meta Business.

La opción compartida interrupt_on_new_message se aplica tanto al modo Cloud API como al modo Web. Cuando está habilitada, un mensaje de WhatsApp más reciente del mismo remitente/chat cancela la respuesta en curso.

Comportamiento personal y empresarial

Para el modo Web, dm_policy y group_policy se aplican en ambos modos. self_chat_mode es solo personal:

self_chat_mode se mantiene exclusivamente para uso personal porque la funcionalidad de chat propio está limitada a la rama personal por diseño. mode selecciona la postura de políticas de ZeroClaw, no un tipo de cuenta de WhatsApp: ambos modos utilizan la misma sesión de dispositivo vinculado.

La comprobación de fromMe también permanece dentro de la rama personal, pero no porque el modo empresarial carezca de un equivalente. El modo empresarial sigue siendo una sesión de dispositivo vinculado de WhatsApp Web, y WhatsApp replica los mensajes salientes del propio operador en los dispositivos vinculados como fromMe en cualquiera de los dos modos. La cuenta vinculada se conserva como un par autorizado, por lo que, en el modo empresarial, ese reflejo puede satisfacer la lista de permitidos y llegar al envío, que es el patrón que #6353 cerró para el modo personal. Ese comportamiento es anterior a este cambio y no se introduce aquí; se señala explícitamente en lugar de darse por descartado, y su corrección se sigue por separado.

Nota de compatibilidad para mode = "business"

El modo empresarial aceptaba anteriormente dm_policy y group_policy, pero nunca consultaba ninguno de los dos, por lo que un canal que se interpretaba como restrictivo respondía a todos los mensajes que recibía. Ahora ambas claves se aplican en el modo empresarial.

dm_policy tiene allowlist de forma predeterminada, por lo que una implementación en modo empresarial que dependiera del comportamiento permisivo anterior debe elegir una de las siguientes opciones:

• Sigue respondiendo a todos - establece dm_policy = "all" y group_policy = "all" explícitamente.
• Mantén la restricción: deja los valores predeterminados y asegúrate de que los remitentes a los que pretendes prestar servicio sean accesibles a través del grupo de pares del canal, mediante [peer_groups.<name>].external_peers.

No esperes a que config validate te lo indique. En mode = "business" informa de que self_chat_mode está inerte y no dice nada sobre dm_policy ni group_policy, precisamente porque esas dos opciones ahora están activas en lugar de inertes. Por tanto, las claves cuyo comportamiento realmente ha cambiado para ti son las que el validador no mencionará. Lee esta sección antes de actualizar; ese es el único aviso que recibe un despliegue en modo empresarial.

passive_group_context = true es opcional y se aplica solo a los chats de grupo de WhatsApp Web. Los mensajes de grupo no dirigidos permitidos se almacenan en el historial de conversación con alcance de sala sin iniciar un turno del agente, enviar reacciones, descargar medios ni llamar al modelo. Más tarde, los mensajes dirigidos en el mismo grupo pueden usar ese contexto pasivo.

Restringiendo qué grupos (allowed_groups)

allowed_groups (modo web) limita el bot a un conjunto específico de chats grupales mediante JID. Es independiente de mode: se aplica tanto en el modo empresarial como en el personal, y se ejecuta antes de la política de tipo de chat. Una lista vacía no es un permiso: lo que significa lo decide group_policy. Con allowlist (el valor predeterminado) o ignore, una lista vacía no admite ningún grupo, mientras que con all admite todos los grupos. Una lista que admite todo no se puede distinguir de una lista que nadie configuró, por lo que el acceso abierto a grupos debe solicitarse explícitamente por nombre. Una lista no vacía descarta todos los mensajes de grupo cuyo JID de chat no coincida con ninguna entrada y sigue haciéndolo con cualquier política, incluida all, por lo que all amplía el valor predeterminado de la lista vacía en lugar de anular una lista explícita. Los mensajes directos siempre omiten este filtro.

Cada entrada coincide con el JID completo del grupo (123456789012345@g.us) o con la parte de usuario del JID: el segmento anterior a @ (123456789012345) — comparado exactamente, no como un prefijo de cadena (así 123 admite 123@g.us pero nunca 123999@g.us). Esto controla la identidad del grupo, que group_policy (tipo de chat) y la lista de अनुमति de remitentes (remitente) no controlan.

[channels.whatsapp.myaccount]
enabled = true
session_path = "/var/lib/zeroclaw/wa.db"
# Operar solo en estos dos grupos; todos los demás grupos se descartan.
allowed_groups = ["120363012345678901@g.us", "120363098765432109"]

Aprobación de herramientas mediante chat (approval_timeout_secs)

Cuando una herramienta necesita aprobación (está en always_ask o el perfil de riesgo no la aprueba automáticamente), el agente publica la solicitud en el chat del que provino el mensaje y espera una respuesta. Responde con el token de la indicación:

a1b2c3 yes
a1b2c3 no
a1b2c3 always

approval_timeout_secs limita esa espera. El valor predeterminado es de 300 segundos, y 0 deniega inmediatamente en lugar de deshabilitar la aprobación, por lo que cero sirve para rechazar todas las herramientas sujetas a aprobación, no para esperar indefinidamente. Cuando se agota el tiempo de espera, la solicitud se deniega y el token se descarta, por lo que una respuesta tardía no puede aprobar una llamada que ya no tiene a nadie esperando.

Quién puede responder. El token es un correlacionador, no una contraseña: viaja en texto plano al chat, por lo que en un grupo todos los miembros pueden leerlo.

Los dos modos difieren, y la diferencia es un límite de seguridad, no un detalle de implementación.

En el modo Web, una respuesta solo se acepta cuando procede del mismo chat en el que se publicó la solicitud y de un interlocutor del que este alias está autorizado a recibir instrucciones. Una respuesta que no supera cualquiera de las dos comprobaciones se registra y se ignora, y la solicitud permanece abierta para que el operador aún pueda responderla. En un grupo, la solicitud lo indica, porque, de lo contrario, no hay forma de saber por qué la respuesta de un espectador no hizo nada.

Los pares autorizados son los que el resolvedor canónico devuelve para este alias, es decir, el grupo de pares cuyo channel apunta a él:

[peer_groups.whatsapp_default]
channel = "whatsapp.personal"   # solo este alias; "whatsapp" sin comillas cubre todos los alias
external_peers = ["+15550100"]

No hay ningún campo allowed_numbers que configurar. Ese era el nombre en v2, y la migración lo incorpora a un grupo de pares como el anterior, por lo que una configuración de v2 sigue funcionando y una configuración de v3 no tiene dónde colocar la clave antigua.

Consulta Grupos de pares para ver la lista completa de campos y el formato del identificador con el que se compara cada canal.

En modo Cloud API, no se aplica ninguna de las dos comprobaciones. Su entrada pendiente es un respondedor sin más, identificado por el token, sin registrar junto a ella ningún chat ni identidad, por lo que el webhook considera que poseer el token otorga autoridad. En un grupo, eso significa que cualquier miembro que pueda leer la solicitud puede responderla, incluso desde otro chat. Hasta que se refuerce esa ruta, una aprobación en modo Cloud solo demuestra que alguien poseía el token y nada más. No autentica ni el chat ni al respondedor, así que prefiere el modo Web siempre que cualquiera de los dos sea importante.

Superficies de configuración

zeroclaw config set channels.whatsapp.<alias>.access_token    # entrada enmascarada, almacenada cifrada

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    # entrada enmascarada, almacenada cifrada

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    # entrada enmascarada, almacenada cifrada

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 es un secreto. Se almacena cifrado, nunca en texto plano en config.toml. Configúralo mediante una de estas opciones, que cifran al escribir:

zeroclaw config set channels.whatsapp.<alias>.access_token    # solicita entrada enmascarada, almacena cifrado

Lo mismo aplica para verify_token y app_secret (Cloud API).

Iniciar y comprobar

Tras configurar un modo, inicia el ejecutor de canales:

zeroclaw channel start

Use zeroclaw channel doctor para una primera comprobación. Para el modo Web, confirma también que el binario se compiló con whatsapp-web; para el modo Cloud API, confirma que el túnel del webhook y el token de verificación de Meta coinciden.