Ir al contenido

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.

  • 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.
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.

En el panel: Campañas → Nueva campaña, elige la conexión y la plantilla. Por la API:

Ventana de terminal
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.

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 (formato NAMED).
  • 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).

Descarga el CSV de ejemplo para empezar:

to,nombre,cupon
5511999990001,Ana,BF10
+55 (21) 99999-0002,Bruno,
ctc_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b,,BF20
  • La fila de encabezado es obligatoria. La columna del destino es to (u otra, con to_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 el ctc_… 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:

Ventana de terminal
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.

Ventana de terminal
curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-F "[email protected]" -F "to_column=to"

El tope es de 100 000 destinatarios por campaña (422 campaign_too_many_recipients).

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.

Ventana de terminal
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" }'
  • 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 con rate_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.

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

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.

  • GET /v1/campaigns/{id}/recipients?status=failed lista los destinatarios por estado: pending, invalid, sending, sent, delivered, read, failed, unknown, skipped.
  • unknown es 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}/report devuelve un CSV con to, 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.completed y campaign.canceled. Los mensajes llevan campaign: { id, recipient_id } en message.sent y message.status. Consulta Eventos.