API y MCP de WhatsApp: conecta un número, envía mensajes y recíbelos por webhook

28 de octubre de 2026 · Equipo Zoosial

Zoosial ofrece una API REST y un servidor MCP para WhatsApp: conectas un número, envías mensajes con una llamada y recibes cada mensaje entrante por webhook firmado. Hay dos formas de conectar el número, por QR (no oficial) o con las credenciales de la Cloud API oficial de Meta, y el mismo endpoint de envío funciona con las dos.

Qué puedes hacer

• Conectar un número por QR: POST /connect/wasender, y consultar el escaneo con GET /accounts/:id/wasender/qr.
• Conectar la Cloud API oficial: POST /connect/whatsapp-cloud.
• Enviar un mensaje de texto: POST /accounts/:id/whatsapp/send con { to, text }. Enruta al proveedor correcto y respeta el límite de envíos.
• Enviar una plantilla aprobada (solo Cloud): el mismo endpoint con { to, template: { name, language, params? } }.
• Listar y crear plantillas (solo Cloud): GET y POST /accounts/:id/whatsapp/templates; nacen en PENDING.
• Recibir mensajes: el webhook message.received, que se registra con POST /hooks.
• Saber de qué anuncio vino un mensaje: data.origin, solo si llegó desde un anuncio de clic a WhatsApp.

Cómo conectar la cuenta

WhatsApp no pasa por OAuth de navegador. Primero crea un perfil con POST /profiles y usa su id como profileId.

• QR (WaSender): POST /connect/wasender { profileId, phone, displayName? } devuelve { accountId, qr, status }. El phone son solo dígitos, de 8 a 15, sin + ni espacios; con + responde 400.
• Cloud API oficial: POST /connect/whatsapp-cloud { profileId, phoneNumberId, accessToken, wabaId?, displayName? }, con un número ya dado de alta en Meta Business. Un número conectado por otro dueño responde 409.
• Embedded Signup de Meta existe en la pantalla /app/whatsapp del panel; no es para agentes.

Detalle en WhatsApp Business.

Ejemplo

Enviar un mensaje:

curl -X POST https://zoosial.com/accounts/acc_456/whatsapp/send \
  -H "Authorization: Bearer $SC_API_KEY" -H "Content-Type: application/json" \
  -d '{"to":"5219990000000","text":"Hola! ¿en qué te ayudo?"}'

Y la forma del evento que recibe tu webhook, con el payload anidado en data:

{ "event": "message.received", "ownerId": "…", "profileId": "prof_123",
  "data": { "accountId": "acc_456", "from": "34600000000", "text": "hola", "msgId": "…", "platform": "whatsapp" } }

Cada entrega lleva X-SocialGate-Signature: sha256=…, un HMAC del cuerpo crudo con tu secret. No vuelvas a serializar el JSON antes de compararlo.

Por MCP

El servidor MCP (https://zoosial.com/mcp) tiene una herramienta para WhatsApp: send_whatsapp, que envía un mensaje desde una cuenta de WhatsApp conectada y está marcada «escribe». El estado de la cuenta se ve con accounts_health. Las herramientas list_conversations y send_dm son solo de Facebook e Instagram. Conectar un número no se hace por MCP, sino en el panel o con la API. Con permiso de solo lectura, el agente no puede enviar. Para recibir, configura un webhook (create_webhook).

Reglas y límites

• Fuera de la ventana de 24 horas desde el último mensaje del cliente, Meta solo acepta plantillas aprobadas.
• La conexión por QR no es la API oficial de Meta: usa la sesión de WhatsApp Web por debajo y existe riesgo de baneo del número. Para producción seria, la documentación recomienda la Cloud API.
• Las plantillas (listarlas, crearlas y enviarlas) funcionan solo con Cloud.
• La documentación indica que el onboarding de coexistencia con QR (mismo número en la app y en la Cloud API) aún no está implementado.
• La página de bandeja indica que la aprobación de Meta para el WhatsApp Business API oficial de Zoosial sigue en proceso; hoy el número se conecta por QR.

Precio

La bandeja, la API, los webhooks y el MCP están incluidos en el plan gratis: 1 perfil con hasta 3 cuentas, sin tarjeta y sin vencimiento. El plan por perfil cuesta $95 MXN al mes + IVA por perfil, con el primero gratis. Más en precios.

Compáralo

Si evalúas otras APIs de mensajería y redes, mira las comparativas y el artículo API para conectar redes sociales. Contrato: /llms.txt.

Preguntas frecuentes

← Todas las integraciones