API de WiCloud

Envía mensajes de WhatsApp, gestiona contactos y listas, y crea campañas desde tus sistemas, n8n u otras herramientas.

Autenticación: Authorization: Bearer wic_…. Crea la clave en tu panel → Integraciones → API e integraciones. Documentación en Markdown para agentes de IA: /llms.txt, /llms-full.txt y GET /api/v1/docs.

Permisos de la clave: lectura, mensajes, contactos, campanas, campanas_enviar, eventos, bandeja, plantillas, estados, canales. Cada ruta indica el que necesita (x-permiso).

Números: mándalos con código de país (+593991234567). Sin código se usa el del WhatsApp de tu cuenta o el que pases en codigoPais.

Protección anti-bloqueo: los mensajes salen por una cola, de a uno por número y con pausas humanas. Las campañas respetan las pausas mínimas y el horario de tu cuenta, y quedan como borrador salvo que la clave tenga campanas_enviar y pidas enviarDirecto.

Errores: siempre traen codigo (estable, para tu lógica) y message (para personas).

Eventos (webhooks): WiCloud te avisa con un POST a tu dirección cuando pasa algo: mensaje.recibido (llegó un mensaje), campana.respuesta (alguien respondió a una campaña), campana.terminada (terminó una campaña), instancia.desconectada (se desconectó un número), instancia.conectada (se conectó un número), contacto.creado (se creó un contacto), contacto.actualizado (se actualizó un contacto), contacto.eliminado (se eliminó un contacto), lista.creada (se creó una lista), lista.actualizada (cambió una lista), campana.creada (se creó una campaña), campana.iniciada (empezó una campaña), campana.pausada (se pausó una campaña), campana.fallida (falló una campaña), mensaje.en_cola (mensaje en cola), mensaje.enviado (mensaje enviado), mensaje.entregado (mensaje entregado), mensaje.leido (mensaje leído), mensaje.fallido (mensaje fallido), contacto.baja (un contacto pidió la baja). Créalos en tu panel o con POST /v1/suscripciones.

Asistentes de IA (MCP): en POST /api/mcp hay un servidor MCP de solo lectura (Streamable HTTP) para Claude, Cursor, n8n u otros clientes MCP, con la misma clave (Authorization: Bearer wic_…; si el cliente no permite headers, ?key=wic_… en la URL, solo en el MCP). Herramientas: cuenta, números, campañas y sus resultados, contactos, listas, estadísticas y, con el permiso bandeja, las conversaciones recibidas.

Cada aviso trae: X-WiCloud-Evento, X-WiCloud-Id (único: si llega dos veces por un reintento, ignora el segundo), X-WiCloud-Timestamp y X-WiCloud-Firma = sha256= + HMAC-SHA256 con tu clave de "<timestamp>.<cuerpo>". Responde 2xx en menos de 10 s; si no, se reintenta a 1 min, 5 min, 30 min, 2 h y 6 h. Tras 20 avisos fallidos seguidos el webhook se pausa solo.

Cuenta

Números

Mensajes

Contactos

Listas

Campañas

Eventos

Conversaciones

Plantillas

Estados

Reportes

Grupos

Canales

Especificación OpenAPI (JSON)