Cuándo usar
- Quieres lanzar campañas desde tu propio sistema, sin abrir la pantalla de Cloud Chat.
- Quieres estimar cuántos contactos alcanza una audiencia antes de gastar en envíos.
- Necesitas seguir el estado de una campaña de forma programática.
Requisitos previos
Crear una campaña dispara el envío. No existe un borrador intermedio en la API, igual que en la pantalla. No uses el endpoint de creación para "montar y revisar después".
- Clave de API de la cuenta.
- Perfil con permiso para campañas. El perfil de agente no puede disparar, ni en la API ni en la pantalla.
Cómo funciona
Verificar el alcance antes de enviar
Existe un endpoint que resuelve la audiencia y devuelve cuántos contactos realmente alcanza. Úsalo antes de crear: es lo que evita descubrir el tamaño real del envío después de que ya salió.
La confirmación obligatoria de destinatarios
En la creación, necesitas declarar cuántos destinatarios esperas alcanzar. El sistema compara ese número con lo que la audiencia realmente resuelve:
- Si coincide, la campaña se crea y entra en la cola de envío.
- Si difiere, la respuesta es un error de conflicto y nada se crea.
Esta es la protección contra envíos no intencionados. Existe precisamente porque no hay borrador: si tu audiencia creció desde la última vez que la consultaste, la solicitud falla en lugar de enviar a más personas de las que esperabas.
Canales disponibles
La creación cubre los tres canales que también cubre la pantalla: WhatsApp, correo electrónico y widget web.
Descubrir plantillas y variables
Como quien llama por la API no ve la pantalla, existen dos endpoints de descubrimiento: uno lista las plantillas disponibles en la cuenta y el otro, las variables que puedes usar. Úsalos para montar el cuerpo de la campaña sin depender de que alguien revise en el panel.
Consultar el estado después
Hay un endpoint de lectura para seguir la campaña creada.
Observaciones
- La referencia completa de los endpoints está en la documentación pública de la API. Las mismas capacidades también están disponibles como herramienta de MCP.
- La campaña creada por la API nace en el mismo estado que la creada por la pantalla, y es el mismo programador quien envía. La API es la puerta de entrada, no un camino de envío diferente.
- Existen límites de destinatarios, por audiencia bruta y por canal. Si la solicitud supera el límite, recibes un error de validación y no se crea nada.