Enviar una campaña de WhatsApp por la API
Envía una campaña de WhatsApp por la API: plantilla de marketing, destinatarios, lanzamiento, cuotas del plan, límites de marketing de Meta y seguimiento de la entrega.
Para enviar una campaña de WhatsApp por la API con Genuka WA, consigues que Meta apruebe una plantilla MARKETING,
creas la campaña con POST /api/v1/campaigns y su lista de destinatarios, y luego
la lanzas con POST /api/v1/campaigns/{id}/launch. Cada destinatario se sigue hasta la lectura,
y Meta factura los mensajes entregados directamente a tu propia cuenta de WhatsApp Business.
Última actualización: 8 de octubre de 2026
Lo que necesitas antes de enviar una campaña
- Un número conectado y su
connectionId— consulta Conectar un número. - Una clave API, usada solo del lado del servidor — consulta Autenticación.
- Un método de pago en tu cuenta de Meta. Genuka es un Tech Provider de Meta, no un BSP: Meta factura
directamente a tu cuenta de WhatsApp Business (WABA), y un cliente incorporado por un Tech Provider debe
agregar su propio método de pago
(Meta, Partners).
Sin él, la plantilla se aprueba, pero cada envío vuelve con el error
131042. - Destinatarios que aceptaron recibir tus mensajes. Es una regla de WhatsApp, no una buena práctica — la sección sobre el consentimiento (opt-in), más abajo, lo explica.
¿Cómo creo la plantilla de marketing?
Fuera de la ventana de atención al cliente de 24 horas, solo se entrega una plantilla aprobada. Una campaña
siempre usa una. Envíala con la categoría MARKETING:
curl -X POST https://wa.genuka.com/api/v1/templates \
-H "Authorization: Bearer $GENUKA_WA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"name": "october_sale",
"language": "en_US",
"category": "MARKETING",
"components": [
{ "type": "BODY",
"text": "Hi {{1}}, 20% off the whole shop until Sunday.",
"example": { "body_text": [["Awa"]] } },
{ "type": "BUTTONS", "buttons": [
{ "type": "URL", "text": "See the offers", "url": "https://example.com/sale" }
] }
]
}'La respuesta es un 201 con el id de la plantilla y su estado. Meta la revisa —
la revisión puede tardar hasta 24 horas
(Meta, Template fundamentals).
El veredicto llega a tus webhooks (template.status_changed) y a
GET /api/v1/templates/{id}. Una campaña solo sale con una plantilla approved.
Cada variable del cuerpo ({{1}}, {{2}}…) necesita un ejemplo, o la plantilla se rechaza. La
referencia de la API cubre los encabezados multimedia, los parámetros con nombre y los botones.
¿Cómo creo y lanzo la campaña?
Crea la campaña
POST /api/v1/campaigns recibe cuatro campos, todos obligatorios: connectionId, templateId, name
y recipients. Cada destinatario lleva su número en formato internacional (+ y código de
país) y sus propias variables. La campaña se crea como draft: todavía no se envía nada.
Lánzala
POST /api/v1/campaigns/{id}/launch envía a todos los destinatarios que siguen en pending y responde con el
recuento: sent, failed, skipped. sent significa que Meta aceptó el mensaje, no que haya llegado —
la entrega y la lectura llegan después, por webhook.
Sigue los estados
Lee los contadores en GET /api/v1/campaigns/{id} y el detalle por destinatario en
GET /api/v1/campaigns/{id}/recipients. La sección de seguimiento, más abajo, cubre ambos.
# 1. Crear la campaña (borrador)
curl -X POST https://wa.genuka.com/api/v1/campaigns \
-H "Authorization: Bearer $GENUKA_WA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"templateId": "tpl_123",
"name": "October sale",
"recipients": [
{ "to": "+237690000001", "variables": ["Awa"] },
{ "to": "+237690000002", "variables": ["Paul"] }
]
}'
# { "data": { "id": "cmp_9", "name": "October sale", "status": "draft", "_count": { "recipients": 2 } } }
# 2. Lanzarla
curl -X POST https://wa.genuka.com/api/v1/campaigns/cmp_9/launch \
-H "Authorization: Bearer $GENUKA_WA_API_KEY"
# { "data": { "sent": 2, "failed": 0, "skipped": 0 } }variables es un arreglo posicional para los parámetros del cuerpo. Para un encabezado multimedia, un botón dinámico
o parámetros con nombre, pasa un objeto en su lugar —
{ "body": [...], "bodyNamed": { "first_name": "Awa" }, "header": {...}, "buttons": [...] } —
la misma forma que al enviar una plantilla. Los valores de una plantilla con parámetros con nombre
van en bodyNamed: si los pones en body, se enviarían como parámetros posicionales.
¿Por qué se rechaza el lanzamiento?
Estas verificaciones se ejecutan antes del primer envío: un lanzamiento rechazado no ha enviado nada. Los rechazos más comunes:
| Estado | Código | Causa |
|---|---|---|
402 | plan_limit_messages | La lista no cabe en lo que queda de la cuota del período. Cuenta cada destinatario pending, incluidos los que luego se excluyen por haberse dado de baja |
402 | subscription_past_due | La prueba o el período pagado ha vencido |
400 | send_template | La plantilla no está approved (en revisión, rechazada, pausada) — el mensaje indica cuál es el caso |
409 | send_config | El número se desconectó de la API en la app WhatsApp Business (coexistencia): vuelve a conectarlo |
409 | number_released | El número se liberó de tu plan: vuelve a conectarlo mediante el Embedded Signup |
403 | account_deactivated | El cliente propietario del número está suspendido |
404 | campaign_not_found | El id no existe o está fuera del alcance de tu clave |
En la creación, un templateId y un connectionId que pertenecen a dos clientes distintos responden
400 template_connection_mismatch, y una lista sin un solo to utilizable responde
400 no_valid_recipients. Los demás códigos están en la referencia de errores.
¿Cuántos mensajes puede enviar una campaña?
Genuka nunca cobra por mensaje; Meta sí cobra sus propias tarifas por mensaje directamente a tu WABA, sin margen de Genuka. Tu plan incluye una cuota de mensajes salientes por número pagado y por período de facturación (sin incluir las tarifas de Meta), compartida entre los envíos por la API y los destinatarios de campañas. La cuota del período es: números pagados × la asignación por número del nivel. El contador vuelve a cero con cada nuevo período: cada mes en una suscripción mensual, en la renovación en una anual.
| Nivel | Máx. de números | Mensajes incluidos por número y por período |
|---|---|---|
| Starter | 5 | 500 |
| Growth | 15 | 5.000 |
| Scale | 100 | 30.000 |
| Enterprise | a medida | a medida |
Ejemplo: 3 números en Growth dan 15.000 mensajes para el período. La prueba gratuita de 7 días funciona con el
nivel Growth y un número, es decir, 5.000 mensajes. Solo se cuentan los mensajes que Meta aceptó: un envío
que Meta rechaza en la llamada no consume nada, pero un mensaje aceptado y luego reportado como failed
por webhook sigue contando. Los precios están en la página de precios y en Markdown en
/pricing.md.
¿Qué límites impone Meta a las campañas de marketing?
La cuota de Genuka no es el único techo. Meta aplica cuatro propios, sea cual sea tu plan:
| Límite de Meta | Qué establece | Qué ves |
|---|---|---|
| Límite de mensajes | Destinatarios únicos que puedes alcanzar fuera de una ventana de atención al cliente, en 24 horas móviles, a nivel del portafolio comercial: 250 para un portafolio nuevo, luego 2,000, 10,000, 100,000, ilimitado (docs) | Administrador de WhatsApp (en inglés, WhatsApp Manager), Account tools > Messaging limits (misma página). El messagingLimitTier de GET /api/v1/numbers?refresh=true es solo indicativo: proviene de un campo que Meta dejó obsoleto y puede estar vacío |
| Límite de marketing por usuario | WhatsApp puede no entregar una plantilla de marketing a alguien que recibe muchas y lee pocas. Espera al menos 24 horas antes de reenviar (docs) | Error 131049 en el webhook de estado, destinatario failed |
| Números de EE. UU. | WhatsApp actualmente no entrega plantillas de marketing a números de teléfono de EE. UU. (misma página) | El destinatario falla |
| Rendimiento | 80 mensajes por segundo por número por defecto, 20 para un número en coexistencia (throughput, coexistence) | El lanzamiento se ajusta a ese ritmo |
El límite de marketing por usuario no está activo actualmente para los mensajes enviados desde o hacia el Espacio Económico Europeo, el Reino Unido, Japón y Corea del Sur (misma página de Meta).
Las plantillas MARKETING de una campaña se ofrecen primero a la
Marketing Messages API de Meta;
si tu cuenta no tiene acceso a ella, el envío recurre al endpoint clásico sin
detener la campaña.
¿Cuánto cuesta una campaña del lado de Meta?
Meta cobra por mensaje entregado, según la tarifa de la categoría de la plantilla y el código de país del destinatario, a tu portafolio comercial (Meta, Pricing). Genuka no agrega ningún margen y nunca gestiona ese pago.
¿Necesito el consentimiento (opt-in) para una campaña de WhatsApp?
Sí. La política de WhatsApp Business solo te permite contactar a alguien que te dio su número y confirmó que quiere recibir tus mensajes (WhatsApp Business Messaging Policy). Meta agrega que la solicitud debe nombrar a tu negocio e indicar claramente a qué está dando su consentimiento la persona, por el canal que prefieras — sitio web, SMS, formulario en papel (Meta, Get opt-in). Una calidad que se mantiene baja durante un período prolongado hace que Meta limite la velocidad del número (misma página).
Genuka aplica por ti las bajas de marketing en las campañas:
- Cuando un usuario detiene los mensajes de marketing desde WhatsApp, Meta lo anuncia por webhook y
Genuka lo registra. Un envío rechazado con
131050("este destinatario eligió dejar de recibir mensajes de marketing") también se registra. - Cuando se lanza una campaña
MARKETING, esos contactos se excluyen antes de cualquier envío y se marcan comoskipped, con el motivo. No consumen ni cuota ni facturación de Meta. - Las campañas
UTILITYyAUTHENTICATIONno se filtran: no son mensajes de marketing.
Una palabra clave propia ("responde STOP") no se interpreta automáticamente: las respuestas te llegan en
message.received, y quitar esos contactos de tus listas depende de ti.
¿Cómo sigo los resultados de una campaña?
GET /api/v1/campaigns/{id} devuelve la campaña, su plantilla, su número y un objeto stats que
cuenta los destinatarios por estado:
{
"data": {
"id": "cmp_9",
"name": "October sale",
"status": "completed",
"template": { "id": "tpl_123", "name": "october_sale", "language": "en_US", "status": "approved" },
"_count": { "recipients": 1200 },
"stats": { "read": 640, "delivered": 410, "sent": 95, "failed": 41, "skipped": 14 }
}
}Cada destinatario se cuenta una sola vez, en su estado más avanzado: un mensaje leído está en read,
no en delivered. La tasa de entrega se calcula entonces como (delivered + read) / (total − skipped).
| Estado | Significado |
|---|---|
pending | Aún no enviado |
sent | Aceptado por Meta |
delivered | Llegó al teléfono |
read | Leído — solo si el destinatario tiene activadas las confirmaciones de lectura |
failed | Rechazado, con el motivo de Meta en errorMessage |
skipped | Excluido en el lanzamiento: se dio de baja del marketing |
Para los fallos, GET /api/v1/campaigns/{id}/recipients?status=failed&limit=1000 lista cada destinatario
con errorMessage, sentAt, deliveredAt, readAt y failedAt (200 filas por defecto, 1.000
como máximo). En tiempo real, suscribe un endpoint a message.delivered, message.read,
message.failed y user_preference.stopped — consulta Webhooks.
¿Cómo reenvío a los destinatarios bloqueados por el límite de marketing?
El límite de marketing por usuario aparece después del envío: Meta acepta el mensaje y luego el webhook
de estado vuelve como failed con el error 131049
(Meta, Per-user limits).
El destinatario pasa a failed, con el texto de Meta en errorMessage (Meta describe este error como
"This message was not delivered to maintain healthy ecosystem engagement"). Volver a llamar a launch
no les reenviará el mensaje: solo toma los destinatarios en pending.
Para intentarlo de nuevo con esas personas, espera al menos 24 horas, lista
GET /api/v1/campaigns/{id}/recipients?status=failed, conserva los que tienen ese motivo (o el
código 131049 recibido en message.failed) y crea una nueva campaña con ellos. En el caso menos frecuente
en que Meta rechaza el envío mismo con 131049, el destinatario sigue en pending, y volver a llamar a
launch 24 horas después lo retoma.
Limitaciones actuales
- El lanzamiento es síncrono y tiene un límite de tiempo. La llamada recorre la lista destinatario
por destinatario: cada envío espera la respuesta de Meta y luego que se guarde su estado, por lo que el ritmo
real se mantiene muy por debajo del techo del número. Pasados unos 2 minutos, la CDN situada delante de la API
responde
524— una página de error, no JSON — mientras el envío continúa en el servidor (Cloudflare, error 524). Limita las campañas a unos cientos de destinatarios y divide una audiencia grande en varias campañas. - Después de un
524, sigue la campaña en lugar de lanzarla de nuevo. ConsultaGET /api/v1/campaigns/{id}hasta questatusdeje de serrunning. Nunca llames alaunchsobre una campaña enrunning: hoy nada lo impide, y dos ejecuciones en paralelo enviarían el mensaje dos veces a los destinatarios que la primera ejecución aún no ha alcanzado. - Una ejecución que dura demasiado se interrumpe. El servidor no deja que una llamada se ejecute indefinidamente. Si la
campaña sigue en
running15 minutos después de la llamada, la ejecución se interrumpió: los destinatarios que siguen enpendingno recibieron el envío, y volver a llamar alaunchlos retoma. - Sin programación. No hay campo de fecha: llama a
launchcuando quieras que salga, desde tu propia tarea programada.
¿Y si prefiero una interfaz en lugar de una API?
Genuka WA no tiene consola de campañas: /api/v1/campaigns es una primitiva de integración (plantilla +
destinatarios + estados). Si quieres segmentar una base de clientes y lanzar campañas sin
escribir código, Genuka Core, la plataforma de gestión comercial de Genuka, lo hace:
clasifica a tus clientes, analiza su comportamiento de compra y lanza campañas segmentadas por WhatsApp, SMS
y correo electrónico.
Preguntas frecuentes
¿Puedo enviar una campaña a contactos que nunca me escribieron?
Sí, con una plantilla aprobada y su consentimiento (opt-in). Para eso existe precisamente una plantilla: es el único mensaje que se entrega fuera de la ventana de 24 horas. El límite de mensajes de Meta (250 destinatarios únicos cada 24 horas para un portafolio nuevo) se aplica a esos envíos.
¿Cuánto cuesta una campaña de WhatsApp con Genuka WA?
Dos conceptos separados. Meta factura cada plantilla entregada a tu portafolio comercial, según la categoría y el país del destinatario. Genuka cobra una suscripción por número de WhatsApp, con una asignación de mensajes incluida, y no aplica ningún margen sobre las tarifas de Meta.
¿Qué pasa si un destinatario se dio de baja?
En una campaña MARKETING, se excluye antes del envío y se marca como skipped. No consume
tu cuota y Meta no te cobra nada por él.
¿Por qué sent es alto pero delivered es bajo?
sent solo significa que Meta aceptó el mensaje. Las confirmaciones de entrega llegan después por webhook; si no
llegan, revisa failed y los errores 131049 (límite de marketing) o 131026 (destinatario inalcanzable).
¿Puedo lanzar la misma campaña de nuevo?
Sí, una vez que ya no está en running (completed o failed): launch entonces solo envía a los destinatarios
que siguen en pending, nunca un mensaje que ya salió. No la lances de nuevo mientras esté en
running, ni siquiera después de un 524: espera a que salga de ese estado, o 15 minutos si se queda en él
(ver las limitaciones más arriba).
Fuentes
- Meta — Messaging limits
- Meta — Per-user marketing template message limits
- Meta — Throughput
- Meta — Pricing on the WhatsApp Business Platform
- Meta — Get opt-in for WhatsApp
- Meta — Template fundamentals
- Meta — Marketing Messages API: get started
- Meta — Partners (Tech Providers and Solution Partners)
- Meta — Error codes
- Meta — Onboard WhatsApp Business app users
- WhatsApp — Business Messaging Policy
- Cloudflare — Error 524: a timeout occurred
- Genuka — genuka.com
Notificaciones de pedidos por WhatsApp desde tu backend
Envía confirmaciones de pedido, avisos de envío y de entrega por WhatsApp desde tu backend: plantillas de utilidad, variables, idempotencia y estados de entrega.
Recibir respuestas y estados de WhatsApp por webhook
Recibe respuestas de WhatsApp y estados de entrega en tu servidor: registra un webhook, verifica la firma HMAC, elimina duplicados, gestiona los reintentos y la reproducción.