Este servicio utiliza la capacidad de dispositivos vinculados de WhatsApp, y no la API oficial de WhatsApp Business; el método de acceso a la cuenta no está respaldado oficialmente por WhatsApp. Los cambios de protocolo, la revocación de dispositivos o las restricciones de la cuenta pueden causar interrupciones. Conecta únicamente cuentas que poseas, cumple los términos de WhatsApp y no lo utilices para mensajes no deseados ni envíos masivos sin consentimiento.
Despliegue y autorización personal
- Crea la aplicación «Agente de cuenta de WhatsApp» en la consola, activa la suscripción y haz clic en desplegar. Los recursos de la instancia son configurados automáticamente por la plataforma.
- Una vez que la instancia esté lista, consulta el código QR en la página de administración. Abre WhatsApp en tu propio teléfono en Configuración → Dispositivos vinculados → Vincular un dispositivo y escanea el código. También puedes introducir tu propio número de teléfono para solicitar un código de emparejamiento y luego confirmarlo en el teléfono.
- Cuando el estado de la página de administración cambie a «Conectado», copia la dirección MCP exclusiva y el token de acceso Bearer.
- Cerrar sesión intentará revocar el dispositivo vinculado y eliminar la sesión local y el historial. Si el resultado del cierre de sesión es incierto, primero revoca ese dispositivo en «Dispositivos vinculados» del teléfono; destruir la instancia eliminará su volumen persistente.
Autenticación y capacidades
Excepto/health y /readyz, las interfaces REST, MCP, de escaneo y de emparejamiento requieren Authorization: Bearer <token de acceso>. El token solo debe colocarse en el encabezado de la solicitud, no en la URL ni en los registros. GET /api/capabilities proporciona las operaciones realmente compatibles con la instancia actual y los límites de retención.
Actualmente se admite: estado de cuenta y conexión, conversaciones y contactos sincronizados con el dispositivo vinculado, eventos de mensajes en tiempo real, lectura de mensajes retenidos localmente, envío y recepción de texto y medios de no más de 10 MiB, respuestas citadas, reacciones con emoji, marcado como leído, así como edición/revocación de mensajes propios, información de grupos y operaciones de un solo miembro permitidas por los permisos de la cuenta y las reglas actuales de WhatsApp. Las modificaciones de grupos siguen siendo validadas por WhatsApp según los permisos de miembros y administradores.
Alcance del historial: solo pueden leerse los mensajes realmente sincronizados con el dispositivo vinculado desde el teléfono, así como los mensajes recibidos mientras el agente está en línea. No se puede garantizar la obtención de todos los mensajes antiguos; localmente se conservan como máximo los 5.000 mensajes más recientes y 2.000 eventos. Cuando existen metadatos de medios, es posible que los medios originales ya no puedan descargarse.
MCP
La página de administración del despliegue proporcionahttps://whatsapp-bot-<实例 ID>.app.acedata.cloud/mcp. Configura esta dirección en un cliente MCP compatible con Streamable HTTP y encabezados de solicitud personalizados, y añade el mismo token Bearer. Las herramientas MCP incluyen whatsapp_capabilities, whatsapp_whoami, whatsapp_chats, whatsapp_contacts, whatsapp_messages, whatsapp_events, whatsapp_send, whatsapp_send_status, whatsapp_media, whatsapp_mark_read, whatsapp_group y whatsapp_group_update.
El Agent puede leer mensajes según sus propias tareas; antes de enviar mensajes a terceros, modificar mensajes o cambiar grupos, debe pedir al usuario que confirme el destinatario y el contenido específicos. Configurar MCP no activará ningún envío por sí mismo.
Ejemplos REST
target debe utilizar el JID devuelto por /api/chats o /api/contacts; no se puede utilizar cualquier número de teléfono para envíos en frío. Primero, el titular debe confirmar el destinatario y el contenido.
action puede ser text, media, edit, revoke o reaction. Para el envío de medios, proporciona media_base64 y mime_type; para respuestas, proporciona reply_to; para edición y revocación, proporciona el message_id propio que pueda consultarse localmente; para reacciones, proporciona message_id y emoji. Puedes descargar medios mediante GET /api/chats/{target}/messages/{id}/media y marcarlos como leídos mediante POST /api/chats/{target}/read.
Los envíos deben incluir una Idempotency-Key de 8 a 128 caracteres. El message_id devuelto es fijo, y el estado es pending, accepted, unknown, delivered o read. accepted solo indica que la conexión local aceptó el envío y no significa que el destinatario lo haya recibido. Cuando ocurra unknown, consulta GET /api/sends/{Idempotency-Key} y los eventos de mensajes; no uses una clave nueva para reenviar el mismo mensaje, a fin de evitar duplicados. El agente no reintentará automáticamente operaciones inciertas.
Los registros de envío no se eliminan automáticamente; después de alcanzar 100.000 registros, la instancia rechaza nuevos envíos (HTTP 507), para evitar envíos duplicados después de que se limpien claves de idempotencia antiguas.
Eventos en tiempo real
GET /api/events?after=<último next_cursor>&wait_ms=25000 admite sondeo largo de hasta 25 segundos; GET /api/events/stream?after=<cursor> proporciona SSE. Los eventos contienen un seq que aumenta monótonamente. El next_cursor de la respuesta debe guardarse en el estado persistente del Agent; si gap=true, significa que los eventos antiguos se han eliminado, y se debe volver a obtener el estado actual de la conversación y continuar desde oldest_cursor. Los eventos de mensajes, el estado de envío y el estado de conexión se informan de forma independiente.
Estados comunes
No se garantiza un historial ilimitado, la disponibilidad a largo plazo de todos los medios ni que todas las operaciones de grupo sean siempre aceptadas por WhatsApp. Cuando necesites comprobar una instancia específica, primero consulta
/api/auth/status y /api/capabilities.