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.
Para notificar a tus clientes sobre un pedido por WhatsApp, crea una plantilla de categoría UTILITY por etapa
(confirmado, enviado, entregado), consigue que Meta la apruebe y luego llama a POST /api/v1/messages desde
tu backend con las variables del pedido. El texto libre solo se permite si el cliente te escribió
en las últimas 24 horas.
Última actualización: 8 de octubre de 2026
¿Qué necesito antes de empezar?
- Un número conectado a Genuka WA y su
connectionId— consulta el inicio rápido. - Una clave API, usada solo del lado del servidor — consulta Autenticación.
- Un método de pago en la cuenta de WhatsApp Business, en Meta. Genuka es un Tech Provider de Meta,
no un BSP: Meta factura directamente a la cuenta, y un cliente incorporado por un Tech Provider debe agregar
su propio método de pago
(Meta, Partners).
Sin él, las plantillas se aprueban, pero cada envío vuelve con el error
131042— consulta error 131042.
¿Qué plantillas debe crear una tienda en línea?
Una plantilla por cada momento en que el cliente espera noticias de su pedido. Tres bastan para empezar:
| Etapa | Plantilla | Variables del cuerpo | Botón |
|---|---|---|---|
| Pedido confirmado | order_confirmed | nombre, número, monto | URL "Ver mi pedido" |
| Pedido enviado | order_shipped | nombre, número, transportista | URL "Seguir mi paquete" |
| Pedido entregado | order_delivered | nombre, número | Ninguno: el mensaje invita a responder |
Para Meta, una plantilla de utilidad se activa por una acción o una solicitud del cliente, es específica de ese cliente y no contiene nada promocional. Las confirmaciones de pedido y los avisos de envío son los ejemplos de manual; una plantilla que mezcla información del pedido con una oferta, una venta adicional o un incentivo de renovación se recategoriza como marketing (documentación de Meta, categorización). Mantén las promociones fuera de estos mensajes.
¿Cómo creo una plantilla de utilidad?
Envía la plantilla
Cada variable del cuerpo necesita un ejemplo en example.body_text, y la variable de un botón URL solo
reemplaza el final de la dirección, con su propio ejemplo.
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": "order_shipped",
"language": "en",
"category": "UTILITY",
"components": [
{ "type": "BODY",
"text": "Hi {{1}}, your order {{2}} is on its way with {{3}}. Track it with the button below.",
"example": { "body_text": [["Awa", "ORD-1042", "DHL"]] } },
{ "type": "BUTTONS", "buttons": [
{ "type": "URL", "text": "Track my parcel",
"url": "https://shop.example.com/track/{{1}}",
"example": ["https://shop.example.com/track/ORD-1042"] }
] }
]
}'En el panel: Plantillas › Nueva plantilla, categoría Utilidad.
Espera la aprobación
El veredicto de Meta llega como un webhook template_status (si tu endpoint está suscrito a
template.status_changed, o a todos los eventos), se puede leer en GET /api/v1/templates/{id} y
se puede recuperar con POST /api/v1/templates/sync si se perdió un webhook. Envía solo una
plantilla approved.
Define un tiempo de vida si el mensaje pierde vigencia
Si un mensaje no se puede entregar, WhatsApp sigue reintentando durante el tiempo de vida de la plantilla: 30 días
por defecto para una plantilla de utilidad, configurable de 30 segundos a 12 horas
(documentación de Meta, time-to-live).
Un "tu repartidor llega en 30 minutos" recibido al día siguiente hace más daño que bien: para ese
tipo de plantilla, pasa messageSendTtlSeconds al crearla.
¿Cómo envío la notificación desde mi backend?
Una llamada por notificación. body rellena {{1}}, {{2}}, {{3}} en orden (variables es un
alias aceptado), y buttons[].text completa la URL del botón.
const API = "https://wa.genuka.com/api/v1";
type Order = { number: string; firstName: string; phone: string; carrier: string };
/** El cuerpo de la respuesta: `data` si tiene éxito; si no, `error` (más `meta` si Meta lo rechazó). */
type ApiResult = {
data?: { messageId: string };
error?: string;
message?: string;
meta?: { retryable?: boolean; code?: number };
};
export async function sendOrderShipped(order: Order): Promise<string> {
const response = await fetch(`${API}/messages`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
connectionId: process.env.GENUKA_WA_CONNECTION_ID,
to: order.phone, // internacional, con el +: "+237699001122"
template: {
name: "order_shipped",
language: "en", // el idioma exacto de la plantilla; si no, el envío apunta a "en_US"
body: [order.firstName, order.number, order.carrier],
buttons: [{ type: "url", text: order.number }],
},
}),
signal: AbortSignal.timeout(15_000),
});
// Un 5xx de la CDN no es JSON: sin este catch, el error de parseo perdería `retryable`
// y la notificación se archivaría como un fallo permanente.
const result = (await response.json().catch(() => ({}))) as ApiResult;
if (!response.ok || !result.data) {
throw Object.assign(new Error(result.message ?? result.error), {
status: response.status,
// Un rechazo permanente (plantilla, número) no vale la pena reintentarlo: meta.retryable lo indica.
retryable: response.status >= 500 || result.meta?.retryable === true,
});
}
return result.data.messageId;
}Un 200 significa que Meta aceptó el mensaje; sigue la entrega por webhook usando este messageId. Para
enviar la misma plantilla a toda una lista de una vez, usa mejor las campañas; cada
tipo de contenido se describe en Enviar mensajes.
¿Cuándo puedo enviar texto libre en lugar de una plantilla?
Cuando el cliente te escribe, se abre una ventana de atención al cliente de 24 horas, y cada nuevo mensaje suyo la reinicia. Mientras está abierta puedes responder con cualquier mensaje; una vez cerrada, solo pasan las plantillas aprobadas (documentación de Meta).
El caso típico: el cliente responde al aviso de envío con "Mañana no estaré en casa". Tu
respuesta puede ser texto simple, citando el mensaje con replyTo:
{
"connectionId": "con_1",
"to": "+237699001122",
"replyTo": "wamid.HBg…",
"text": "Anotado, el repartidor volverá el jueves entre las 2 y las 4 p. m."
}En la factura, Meta no cobra los mensajes que no son plantillas, y una plantilla de utilidad entregada dentro de una ventana abierta también es gratuita (precios de Meta).
Fuera de la ventana, el texto libre falla, pero no en el momento del envío. En nuestras pruebas con un número real,
Meta lo aceptó con un messageId y luego lo descartó: por lo general sigue un estado failed con el error
131047
(códigos de error de Meta);
a veces no llega ningún estado. Así que no esperes el fallo: Genuka WA no bloquea el
envío, pero te advierte en la respuesta, y es esa advertencia la que debes tener en cuenta:
{
"data": {
"messageId": "wamid.HBg…",
"warning": { "code": "outside_service_window", "message": "…" }
}
}outside_service_window significa que el último mensaje del cliente tiene más de 24 horas: envía una
plantilla en su lugar. unverified_service_window solo significa que no tenemos registrado ningún mensaje entrante de ese
contacto, lo que no demuestra que la ventana esté cerrada. Vigila el estado del mensaje y
reenvíalo como plantilla solo si llega failed con 131047, o si no llega nada: reenviar de inmediato
puede hacer que la misma notificación se entregue dos veces.
¿Cómo evito enviar la misma notificación dos veces?
La API no tiene clave de idempotencia: es tu backend el que garantiza que un pedido reciba cada notificación una sola vez. La forma más sencilla es una tabla cuya clave primaria es el par pedido + etapa.
create table order_notifications (
order_id text not null,
event text not null, -- confirmed | shipped | delivered
status text not null default 'pending',
message_id text unique, -- el wamid devuelto por Genuka WA
error_code integer,
created_at timestamptz not null default now(),
primary key (order_id, event)
);import { Pool } from "pg";
const db = new Pool();
export async function notifyOnce(orderId: string, event: string, send: () => Promise<string>) {
// 1. Reservar: una segunda llamada para el mismo pedido y la misma etapa no hace nada.
const claimed = await db.query(
"insert into order_notifications (order_id, event) values ($1, $2) on conflict do nothing",
[orderId, event],
);
if (claimed.rowCount === 0) return;
try {
// 2. Enviar, 3. guardar el wamid: es lo que vincula los estados posteriores con esta fila.
const messageId = await send();
await db.query(
"update order_notifications set status = 'sent', message_id = $3 where order_id = $1 and event = $2",
[orderId, event, messageId],
);
} catch (error) {
if ((error as { retryable?: boolean }).retryable === true) {
// Liberar la reserva: la próxima ejecución del job lo intentará de nuevo.
await db.query("delete from order_notifications where order_id = $1 and event = $2", [orderId, event]);
} else {
await db.query(
"update order_notifications set status = 'failed' where order_id = $1 and event = $2",
[orderId, event],
);
}
throw error;
}
}
// await notifyOnce(order.id, "shipped", () => sendOrderShipped(order));Un timeout de red es ambiguo: Meta pudo haber aceptado el mensaje antes de que se perdiera la respuesta. Este código lo archiva como fallo en lugar de arriesgarse a un duplicado. Si, para tu tienda, un duplicado ocasional es preferible a una confirmación perdida, trata también los timeouts como reintentables.
¿Cómo sigo la entrega de cada notificación?
Los estados llegan a tu webhook con el tipo message_status. data.id es el messageId devuelto en el
momento del envío, y data.status es sent, delivered, read o failed. En caso de fallo,
data.errors[0].code contiene el código de Meta
(documentación de Meta, statuses).
const RANK: Record<string, number> = { pending: 0, sent: 1, delivered: 2, read: 3, failed: 4 };
if (event.type === "message_status") {
const { id: messageId, status, errors } = event.data;
const row = await findNotificationByMessageId(messageId);
// Los estados pueden llegar desordenados: un estado nunca retrocede,
// y `failed` es definitivo.
if (row && row.status !== "failed" && (RANK[status] ?? -1) > RANK[row.status]) {
await setNotificationStatus(messageId, status, errors?.[0]?.code ?? null);
}
}Para Meta, read significa que el mensaje se mostró en un chat abierto en el dispositivo del cliente; no
construyas lógica de negocio que dependa de él. La verificación de la firma y la eliminación de duplicados se explican en
Recibir respuestas y estados por webhook.
¿Con qué errores me encontraré con más frecuencia?
| Error | Dónde leerlo | Significado | Qué hacer |
|---|---|---|---|
400 missing_fields | Respuesta | Falta connectionId o to | Completa la solicitud |
400 recipient_is_sender | Respuesta | to es el propio número emisor | Cambia el destinatario |
402 subscription_past_due | Respuesta | La prueba o el período pagado ha vencido: no se envía nada hasta que se renueve | Renueva el plan y luego reenvía lo que notifyOnce archivó como failed |
402 plan_limit_messages | Respuesta | La asignación de mensajes del período se agotó | Agrega números o cambia de plan |
404 connection_not_found | Respuesta | El connectionId no existe o está fuera del alcance de tu clave | Verifica el id y la clave |
409 number_released | Respuesta | El número se liberó de tu plan | Vuelve a conectarlo mediante el Embedded Signup |
403 account_deactivated | Respuesta | El cliente propietario del número está suspendido | Restablece el cliente desde su página en el panel |
132001 | meta.code o estado failed | La plantilla no existe en ese idioma o no está aprobada | Verifica el nombre, el idioma y el estado |
132000 | meta.code o estado failed | El número de variables difiere del de la plantilla | Ajusta body a {{1}}…{{n}} |
131026 | Estado failed | Mensaje imposible de entregar, p. ej. número sin WhatsApp | Recurre al correo electrónico o al SMS |
131047 | Estado failed, a veces nunca recibido | Texto libre enviado más de 24 h después del último mensaje del cliente | Envía una plantilla; ten en cuenta el warning de la respuesta |
130429 | meta.code | Se alcanzó el rendimiento máximo de la Cloud API | Reintenta con un tiempo de espera creciente |
131042 | meta.code o estado failed | Problema con el método de pago en la cuenta de Meta | El cliente corrige la facturación del lado de Meta — consulta error 131042 |
Los significados de los códigos de Meta provienen de su lista de códigos de error.
Preguntas frecuentes
¿Cuánto cuesta una notificación de pedido por WhatsApp?
Meta cobra las plantillas entregadas según la categoría y el país del destinatario, y las factura directamente a la cuenta de WhatsApp Business del comerciante; una plantilla de utilidad entregada dentro de una ventana de atención al cliente abierta es gratuita (precios de Meta). Genuka WA no aplica ningún margen sobre esas tarifas: pagas una suscripción por número, con una asignación de mensajes — consulta los planes.
¿Puedo incluir un código promocional en la confirmación del pedido?
No. Una oferta o una venta adicional dentro de una plantilla de utilidad hace que Meta la recategorice como marketing. Envía la promoción por separado, en una plantilla de marketing, a los clientes que aceptaron recibirlas.
¿Necesito el consentimiento del cliente?
Sí. Meta te pide indicar claramente que la persona acepta recibir mensajes de tu negocio, y nombrar ese negocio (documentación de Meta, opt-in). Una casilla "Recibir las novedades de mi pedido de [Nombre de la tienda] por WhatsApp" en el checkout, guardada con el pedido, cumple ambas condiciones.
¿Y si el cliente no tiene cuenta de WhatsApp?
El estado vuelve como failed con el código 131026. No lo reintentes: envía la misma información por
correo electrónico o SMS.
Tengo varias tiendas: ¿cómo elijo el número emisor?
Cada tienda conecta su número y obtiene su propio connectionId; eso es lo que decide desde dónde sale el
mensaje. Una clave de socio alcanza todas tus tiendas, una clave de cliente solo una — consulta
Autenticación y, para encontrar el número de una tienda,
Conectar un número.
Fuentes
Enviar un OTP por WhatsApp con Node.js
Envía códigos de un solo uso (OTP) por WhatsApp desde Node.js con Genuka WA: plantilla de autenticación, botón para copiar el código, vencimiento, verificación y respaldo por SMS.
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.