Genuka WA docs

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:

EtapaPlantillaVariables del cuerpoBotón
Pedido confirmadoorder_confirmednombre, número, montoURL "Ver mi pedido"
Pedido enviadoorder_shippednombre, número, transportistaURL "Seguir mi paquete"
Pedido entregadoorder_deliverednombre, númeroNinguno: 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.

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": "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.

send-order-shipped.ts
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:

POST /api/v1/messages
{
  "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:

200 OK — con una advertencia
{
  "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.

schema.sql
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)
);
notify-once.ts
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).

En tu receptor de webhooks (firma ya verificada)
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?

ErrorDónde leerloSignificadoQué hacer
400 missing_fieldsRespuestaFalta connectionId o toCompleta la solicitud
400 recipient_is_senderRespuestato es el propio número emisorCambia el destinatario
402 subscription_past_dueRespuestaLa prueba o el período pagado ha vencido: no se envía nada hasta que se renueveRenueva el plan y luego reenvía lo que notifyOnce archivó como failed
402 plan_limit_messagesRespuestaLa asignación de mensajes del período se agotóAgrega números o cambia de plan
404 connection_not_foundRespuestaEl connectionId no existe o está fuera del alcance de tu claveVerifica el id y la clave
409 number_releasedRespuestaEl número se liberó de tu planVuelve a conectarlo mediante el Embedded Signup
403 account_deactivatedRespuestaEl cliente propietario del número está suspendidoRestablece el cliente desde su página en el panel
132001meta.code o estado failedLa plantilla no existe en ese idioma o no está aprobadaVerifica el nombre, el idioma y el estado
132000meta.code o estado failedEl número de variables difiere del de la plantillaAjusta body a {{1}}…{{n}}
131026Estado failedMensaje imposible de entregar, p. ej. número sin WhatsAppRecurre al correo electrónico o al SMS
131047Estado failed, a veces nunca recibidoTexto libre enviado más de 24 h después del último mensaje del clienteEnvía una plantilla; ten en cuenta el warning de la respuesta
130429meta.codeSe alcanzó el rendimiento máximo de la Cloud APIReintenta con un tiempo de espera creciente
131042meta.code o estado failedProblema con el método de pago en la cuenta de MetaEl 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

En esta página