Buenas prácticas

Guía consolidada para integrar Wis.Chat en producción de forma robusta. Incluye recomendaciones sobre calentamiento, idempotencia, manejo de errores, retries y todo lo que necesitas para que tu integración sea estable a largo plazo.

Las tres reglas de oro

Las que el manual oficial enfatiza por encima de todo:

Calentamiento de número (warming)

Cuando habilitas un número nuevo en WhatsApp Business, tu límite inicial es bajo (~250 conversaciones únicas iniciadas en 24h). Subir este límite requiere un patrón gradual, consistente y de buena calidad.

Plan de calentamiento sugerido

Idempotencia

Si tu sistema se cae mientras está enviando, podrías reintentar el mismo mensaje y enviarlo dos veces al mismo cliente. Para evitarlo, lleva en tu propia base de datos un registro de envíos con un id_local único de tu lado, y guarda el wamid que devuelve la API. Antes de cada envío, verifica si ese id_local ya tiene un wamid asignado:

// Pseudocódigo — la tabla "mis_envios_wsp" es TUYA, en tu propia base de datos.
// id_local: identificador único de tu negocio (ej: id de factura, ticket, OTP, etc.)
function enviarIdempotente($idLocal, $payload) {
    // 1. ¿Ya tengo un wamid para este id_local?
    $existing = $db->query(
        "SELECT wamid FROM mis_envios_wsp WHERE id_local = ?",
        [$idLocal]
    );
    if ($existing && $existing['wamid']) {
        return $existing['wamid']; // ya enviado, no duplico
    }

    // 2. Reservo el id_local con estado 'pending' antes de la llamada HTTP
    $db->upsert('mis_envios_wsp', [
        'id_local' => $idLocal,
        'estado'   => 'pending',
    ]);

    // 3. Llamo a la API de Wis.Chat con retry
    $wamid = enviarConReintento(...);

    // 4. Persisto el wamid retornado en MI tabla
    $db->update('mis_envios_wsp',
        ['wamid' => $wamid, 'estado' => 'sent'],
        ['id_local' => $idLocal]
    );
    return $wamid;
}

Rate limiting y throttling

Aunque Wis.Chat es eficiente, Meta impone límites. Si vas a enviar muchos mensajes, no los dispares todos a la vez. Implementa una cola con throttling:

Ventana de 24 horas

Una de las reglas más importantes de WhatsApp Business: sólo puedes enviar texto libre, multimedia o interactivos dentro de las 24 horas posteriores al último mensaje del cliente. Fuera de esa ventana, sólo plantillas aprobadas.

Webhooks robustos

Los webhooks son cómo recibes estados de mensaje y respuestas de los clientes. Algunas reglas:

• Responde rápido (200 OK en menos de 5s). Procesa pesado de forma asincrónica con una cola.
• Acepta idempotencia. Meta puede reenviar el mismo evento si no respondiste a tiempo. Usa id del evento para deduplicar.
• Valida el origen. El gateway firma los payloads de webhook con el secret de tu línea — verifica la firma.
• Loguéa todo. Si algo no cuadra, los logs son tu única fuente de verdad.

Seguridad

Lo que NO hacer

Checklist de producción

Antes de poner una integración en producción, verifica:

Soporte

Si después de seguir estas prácticas sigues teniendo problemas, no dudes en contactarnos: