Plantillas
Campañas en WhatsApp
Plantilla aprobada + lista CSV/JSON + variables + programación: cómo armar, enviar, seguir y reanudar una campaña.
Una campaña envía una plantilla aprobada a una lista de contactos, al ritmo del número y dentro del nivel de 24 horas del portafolio. Solo existe en WhatsApp: Instagram y Messenger no permiten envíos masivos.
Antes de empezar
Sección titulada «Antes de empezar»- Una conexión de WhatsApp Activa o Restringida (consulta Conectar WhatsApp).
- Una plantilla Aprobada de la categoría Marketing o Utilidad en esa conexión.
- Una clave con el permiso
send(para crear y lanzar) o un miembro con rol de propietario, admin o dev en el panel. El rol viewer solo lee.
Ciclo de vida
Sección titulada «Ciclo de vida»| Estado | Qué significa |
|---|---|
draft |
Borrador. Solo aquí se pueden cambiar plantilla, variables y destinatarios |
scheduled |
Programada para scheduled_at |
running |
Enviando |
waiting_limit |
Se agotó el nivel de 24 h del portafolio; vuelve sola en limit_wait_until |
paused |
Pausada por alguien |
auto_paused |
Pausada por Messajo para proteger el número (consulta Pausas) |
completed |
No quedó ningún destinatario en la cola |
canceled |
Cancelada; los destinatarios en la cola pasan a skipped |
El nombre y la velocidad (rate_limit_mps) también cambian en scheduled, paused y auto_paused. Editar otra cosa fuera del borrador devuelve 409 campaign_not_editable; una acción que no vale en el estado actual devuelve 409 campaign_invalid_state.
1. Crear el borrador
Sección titulada «1. Crear el borrador»En el panel: Campañas → Nueva campaña, elige la conexión y la plantilla. Por la API:
curl https://api.messajo.com/v1/campaigns \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Black Friday", "connection_id": "conn_...", "template": { "name": "promo_bf", "language": "es" }, "variables": { "body": [ { "contact": "display_name", "default": "cliente" }, { "column": "cupon" } ] } }'La respuesta es la campaña en draft. Plantilla no aprobada o que no es de marketing/utilidad → 422 campaign_template_not_approved.
2. Mapear las variables
Sección titulada «2. Mapear las variables»Cada parámetro de la plantilla necesita un origen. Si falta alguno → 422 campaign_template_mapping_invalid, con el parámetro en details.
| Origen | Ejemplo | De dónde sale el valor |
|---|---|---|
| Columna | { "column": "cupon", "default": "BF10" } |
columna del CSV o clave de variables en el JSON |
| Fijo | { "value": "hasta el domingo" } |
el mismo texto para todos |
| Contacto | { "contact": "display_name", "default": "cliente" } |
nombre del contacto, cuando Messajo lo conoce |
body: lista en el orden de{{1}},{{2}}… (formato posicional) u objeto por nombre (formatoNAMED).header:{ "params": [...] }para texto,{ "media_id": "med_..." }para imagen, video o documento, o{ "location": {...} }.buttons:[{ "index": 0, "param": {...} }]para URL dinámica, código de cupón y payload.
Usa default cuando la columna puede venir vacía. Sin default, la fila queda invalid con el motivo missing_variable:<columna>. Un valor de más de 1024 caracteres queda invalid (variable_too_long).
3. Subir la lista
Sección titulada «3. Subir la lista»Descarga el CSV de ejemplo para empezar:
to,nombre,cupon5511999990001,Ana,BF10+55 (21) 99999-0002,Bruno,ctc_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b,,BF20- La fila de encabezado es obligatoria. La columna del destino es
to(u otra, conto_column); las demás pasan a ser variables. - Separador
,,;o tabulador. Se acepta el BOM de Excel. - El destino puede ser un teléfono (Messajo quita
+ ( ) - .y espacios; de 8 a 15 dígitos), un BSUID o elctc_…de un contacto de la organización. - Los repetidos se ignoran y se cuentan en
rows_duplicate.
Hasta 10 000 destinatarios por llamada van en el cuerpo, en JSON, y la importación vuelve terminada:
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "recipients": [ { "to": "5511999990001", "variables": { "cupon": "BF10" } } ] }'Un archivo (CSV, JSON o NDJSON, hasta 20 MiB) va por multipart y vuelve 202 con la importación en cola. Síguela en GET /v1/campaigns/{id}/imports/{import_id}: los primeros 100 errores salen en errors con fila, columna y código.
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \ -H "Authorization: Bearer $MESSAJO_API_KEY" \El tope es de 100 000 destinatarios por campaña (422 campaign_too_many_recipients).
4. Revisar la vista previa
Sección titulada «4. Revisar la vista previa»POST /v1/campaigns/{id}/preview (o el paso Vista previa en el panel) muestra los primeros mensajes ya armados, con el cuerpo y los parámetros reemplazados. Revísala antes de programar: un mensaje equivocado no vuelve.
5. Programar o empezar ya
Sección titulada «5. Programar o empezar ya»curl -X POST https://api.messajo.com/v1/campaigns/cmp_.../schedule \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "scheduled_at": "2026-11-27T12:00:00Z" }'scheduled_atentre 1 minuto y 90 días adelante (422campaign_schedule_invalid).- Necesita al menos un destinatario válido (
campaign_no_recipients) y ninguna importación en curso (campaign_import_in_progress). POST /startlanza ahora;POST /unschedulevuelve a borrador.
Velocidad y el nivel del portafolio
Sección titulada «Velocidad y el nivel del portafolio»- Velocidad: por defecto, el 80 % del caudal del número (
send_rate_mps); el 20 % restante queda para los envíos de la API. Ajústala conrate_limit_mps, de 1 hasta el caudal del número. - Nivel de 24 h: Meta limita cuántos contactos únicos reciben plantillas por día (250, 2000, 10 000, 100 000 o ilimitado). El límite es del portafolio: todos los números del mismo Business comparten el nivel. Messajo se detiene en el 95 % del nivel y la campaña pasa a
waiting_limit; cuando los envíos más antiguos salen de la ventana de 24 horas, vuelve sola. - Un contacto con la ventana de atención abierta no gasta nivel.
- El contador solo ve lo que sale por Messajo. Si también envías con otra herramienta en el mismo portafolio, deja margen.
GET /v1/campaigns/{id} trae estimate: destinatarios válidos, velocidad efectiva, duración estimada y cuánto queda del nivel.
Pausas y qué hacer
Sección titulada «Pausas y qué hacer»Messajo pausa solo (auto_paused), avisa por correo a propietarios, admins y a quien creó la campaña, y emite campaign.paused con auto: true. Para continuar, POST /resume (o Reanudar en el panel): reanudar acepta la calidad actual como nueva referencia.
pause_reason |
Por qué | Qué hacer |
|---|---|---|
quality_low |
Bajó la calidad del número (o el envío quedó limitado) | Revisa contenido y lista; insistir baja la calidad y el nivel |
template_paused |
La plantilla dejó de estar Aprobada | Espera a que vuelva a Aprobada en Plantillas |
template_quality_low |
Bajó la calidad de la plantilla | Ajusta la plantilla o la lista: mucha gente bloquea o denuncia |
error_rate |
20 % o más de fallos en los últimos 100 envíos | Descarga el informe y revisa los códigos |
marketing_limit |
10 % o más de 131049 |
Consulta abajo |
spam_limit |
Meta respondió 131048 (sospecha de spam) |
Espera unas horas y baja la velocidad |
policy |
Bloqueo por política o token caído | Resuélvelo en la conexión; puede pedir reconexión |
connection_not_active |
La conexión no está activa | Reconecta y reanuda |
spend_cap |
Se alcanzó el tope de gasto del mes | Sube el tope en Configuración → Costos o espera al próximo mes, y reanuda |
manual |
Alguien la pausó | Reanuda cuando quieras |
131049 y las 24 horas
Sección titulada «131049 y las 24 horas»marketing_limit_reached (131049) es Meta frenando el marketing a quien ya recibió demasiado. No es un problema del número y no sirve repetir enseguida: el contacto solo vuelve a recibir después de un tiempo que Meta no informa (en la práctica, un día o más). Termina la campaña, espera al menos 24 horas y usa Duplicar con recipients: "failed" para enviar solo a quienes fallaron.
Seguimiento e informe
Sección titulada «Seguimiento e informe»GET /v1/campaigns/{id}/recipients?status=failedlista los destinatarios por estado:pending,invalid,sending,sent,delivered,read,failed,unknown,skipped.unknownes un envío que puede haber salido (caída de Meta o del proceso a mitad de camino). Messajo nunca reenvía a ciegas; si Meta manda el estado después, el destinatario se actualiza.GET /v1/campaigns/{id}/reportdevuelve un CSV conto,contact_id,status,message_id,external_id,error_code,meta_code, las fechas y las columnas de variables.- Los estados de entrega siguen llegando hasta 72 horas después de
completed. - Eventos:
campaign.scheduled,campaign.started,campaign.paused,campaign.resumed,campaign.progress(como máximo 1 por minuto),campaign.completedycampaign.canceled. Los mensajes llevancampaign: { id, recipient_id }enmessage.sentymessage.status. Consulta Eventos.