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
GET /api/v1/cuenta— Probar la conexión: tu cuenta, plan, permisos de la clave y límites
Números
GET /api/v1/instancias— Tus números de WhatsApp y si están conectadosGET /api/v1/instancias/{id}— Un número: conexión, calidad, cupo, motor y si es apto para campañas
Mensajes
POST /api/v1/mensajes— Enviar un mensaje (texto, archivo o plantilla) a un númeroGET /api/v1/mensajes/{id}— Estado de un mensajeDELETE /api/v1/mensajes/{id}— Cancelar un mensaje que todavía está en cola
Contactos
GET /api/v1/contactos— Buscar contactosPOST /api/v1/contactos— Crear o actualizar un contacto (por número)GET /api/v1/contactos/{id}— Un contacto, con sus listasPATCH /api/v1/contactos/{id}— Editar un contactoDELETE /api/v1/contactos/{id}— Borrar un contacto (sale de todas sus listas)POST /api/v1/contactos/eliminar— Borrar varios contactos (por id o por número, máximo 500)POST /api/v1/contactos/importar— Importar contactos (lista, CSV o URL pública; máximo 2000)GET /api/v1/contactos/duplicados— Posibles contactos duplicados (no cambia nada)GET /api/v1/bajas— Bajas automáticas: si están activas y qué palabras las disparanPATCH /api/v1/bajas— Cambiar las bajas automáticasPOST /api/v1/contactos/completar-datos— Completar nombre, foto y si es empresa desde WhatsApp (solo campos vacíos, hasta 300, por detrás)
Listas
GET /api/v1/listas— Tus listas de contactosPOST /api/v1/listas— Crear una lista (si ya existe una con ese nombre, la devuelve)GET /api/v1/listas/{id}— Una lista con sus contactos (paginado)PATCH /api/v1/listas/{id}— Cambiar nombre, descripción o colorDELETE /api/v1/listas/{id}— Borrar la lista (los contactos se conservan)POST /api/v1/listas/{id}/duplicar— Copiar la lista con sus contactosPOST /api/v1/listas/{id}/vaciar— Sacar todos los contactos de la lista (siguen en la cuenta)POST /api/v1/listas/mover— Mover (o copiar) contactos de una lista a otraPOST /api/v1/listas/{id}/contactos— Agregar contactos a una lista (por id o por número; los números nuevos se crean)DELETE /api/v1/listas/{id}/contactos/{contactoId}— Quitar un contacto de una lista
Campañas
GET /api/v1/campanas— Tus campañas a contactosPOST /api/v1/campanas— Crear una campaña (queda como borrador salvo enviarDirecto + permiso campanas_enviar)GET /api/v1/campanas/{id}— Estado y resultados de una campañaPATCH /api/v1/campanas/{id}— Editar una campaña en borrador, pendiente o no enviadaDELETE /api/v1/campanas/{id}— Borrar una campaña y su historial (no si está enviando)GET /api/v1/campanas/{id}/destinatarios— Destinatarios con su estadoGET /api/v1/campanas/{id}/validar— Revisar antes de enviar: a cuántos, por qué números, cuándo, problemas y avisosGET /api/v1/campanas/{id}/respuestas— Quién respondió y qué dijo primeroPOST /api/v1/campanas/{id}/pausar— Pausar una campaña que está enviandoPOST /api/v1/campanas/{id}/reanudar— Reanudar una campaña pausadaPOST /api/v1/campanas/{id}/cancelar— Cancelar una campaña (los pendientes no salen)POST /api/v1/campanas/{id}/reintentar— Reintentar los envíos fallidosPOST /api/v1/campanas/{id}/duplicar— Copiar la campaña como borrador nuevoPOST /api/v1/campanas/{id}/enviar— Aprobar y enviar un borrador
Eventos
GET /api/v1/eventos— Los eventos que se pueden recibir, con un ejemplo de cada unoGET /api/v1/suscripciones— Tus webhooksPOST /api/v1/suscripciones— Crear un webhook (devuelve la clave para verificar la firma, una sola vez)DELETE /api/v1/suscripciones/{id}— Borrar un webhook
Conversaciones
GET /api/v1/conversaciones— Buscar chats (sin responder, no leídos, por número o texto)GET /api/v1/conversaciones/{id}— Los últimos mensajes de un chat
Plantillas
GET /api/v1/plantillas— Tus plantillas y las globalesPOST /api/v1/plantillas— Crear una plantilla (texto o archivo)GET /api/v1/plantillas/{id}— Una plantillaPATCH /api/v1/plantillas/{id}— Editar una plantilla propiaDELETE /api/v1/plantillas/{id}— Borrar una plantilla propiaPOST /api/v1/plantillas/{id}/previsualizar— Cómo quedaría para un contacto y qué variables faltan
Estados
GET /api/v1/estados— Estados publicados en las últimas 24 hPOST /api/v1/estados— Publicar un estado (texto con color y fuente, o imagen/video con pie)DELETE /api/v1/estados/{id}— Pedir a WhatsApp que borre un estado publicado
Reportes
GET /api/v1/estadisticas— Resumen de los últimos N díasGET /api/v1/reportes— Reporte por campañas, números, listas o motivos de fallo
Grupos
GET /api/v1/grupos— Tus grupos de WhatsApp (sincronizados en el panel)GET /api/v1/campanas-grupos— Tus campañas a gruposPOST /api/v1/campanas-grupos— Enviar (o programar) una campaña a grupos — sale de verdadPOST /api/v1/campanas-grupos/validar— Revisar una campaña a grupos sin crearla (grupos, participantes y avisos)GET /api/v1/campanas-grupos/{id}— Una campaña a grupos, con entregados y leídos por grupo (48 h)
Canales
GET /api/v1/canales— Canales de WhatsApp de un númeroGET /api/v1/canales/{jid}/publicaciones— Últimas publicaciones de un canal, con vistas y reaccionesPOST /api/v1/canales/{jid}/publicar— Publicar texto, imagen o video en un canal