Genuka WA docs

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:

POST /api/v1/templates
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:

EstadoCódigoCausa
402plan_limit_messagesLa 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
402subscription_past_dueLa prueba o el período pagado ha vencido
400send_templateLa plantilla no está approved (en revisión, rechazada, pausada) — el mensaje indica cuál es el caso
409send_configEl número se desconectó de la API en la app WhatsApp Business (coexistencia): vuelve a conectarlo
409number_releasedEl número se liberó de tu plan: vuelve a conectarlo mediante el Embedded Signup
403account_deactivatedEl cliente propietario del número está suspendido
404campaign_not_foundEl 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.

NivelMáx. de númerosMensajes incluidos por número y por período
Starter5500
Growth155.000
Scale10030.000
Enterprisea medidaa 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 MetaQué estableceQué ves
Límite de mensajesDestinatarios ú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 usuarioWhatsApp 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
Rendimiento80 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 como skipped, con el motivo. No consumen ni cuota ni facturación de Meta.
  • Las campañas UTILITY y AUTHENTICATION no 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:

GET /api/v1/campaigns/cmp_9
{
  "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).

EstadoSignificado
pendingAún no enviado
sentAceptado por Meta
deliveredLlegó al teléfono
readLeído — solo si el destinatario tiene activadas las confirmaciones de lectura
failedRechazado, con el motivo de Meta en errorMessage
skippedExcluido 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. Consulta GET /api/v1/campaigns/{id} hasta que status deje de ser running. Nunca llames a launch sobre una campaña en running: 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 running 15 minutos después de la llamada, la ejecución se interrumpió: los destinatarios que siguen en pending no recibieron el envío, y volver a llamar a launch los retoma.
  • Sin programación. No hay campo de fecha: llama a launch cuando 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

En esta página