Envío de Mensajes y Opt-in

Aprenda a enviar mensajes de WhatsApp desde los módulos de ALTUM ERP y a gestionar correctamente el consentimiento de sus clientes para recibir comunicaciones por este canal.

Requisitos previos

• Integración de WhatsApp Business configurada y habilitada (consulte Configuración).
• Plantillas registradas para los tipos de mensaje a usar (consulte Plantillas).
• Para mensajes que no sean Ticket: el cliente debe tener el opt-in activado.

Cómo se envía un mensaje

ALTUM ERP determina automáticamente el número de destino siguiendo esta lógica:

1. Si se proporcionó un teléfono de destino explícito al solicitar el envío, se usa ese número.
2. En caso contrario, se usa el campo telefonoWhatsapp registrado en el perfil del cliente.
3. Si ninguno está disponible, el envío falla con el mensaje “Se requiere clienteId o telefonoDestino”.

El número se valida y convierte a formato E.164 antes del envío. Si la validación falla, el envío se cancela.

Estados de un mensaje

Cada mensaje pasa por los siguientes estados:

Estado	Descripción
PENDIENTE	El mensaje fue registrado en el sistema pero aún no se envió a la API de Meta.
ENVIADO	La API de Meta aceptó el mensaje. Incluye el apiMessageId de Meta.
FALLIDO	La API de Meta rechazó el mensaje o hubo un error de red. El campo errorCode y errorMessage contienen el detalle.

Los mensajes fallidos quedan registrados en el historial visible en Configuración → WhatsApp Business → Mensajes.

Códigos de error frecuentes

Código	Significado
AUTH_FAILED	El Access Token no es válido o expiró. Actualícelo en la configuración.
RATE_LIMIT	Se superó el límite de mensajes de la API de Meta en el período actual.
INVALID_PHONE	El número de teléfono no pudo validarse en formato E.164.
TEMPLATE_ERROR	La plantilla no está aprobada o sus parámetros no coinciden con la configuración de Meta.
UNKNOWN_ERROR	Error no clasificado; revise el errorMessage para más detalle.

Opt-in: consentimiento del cliente

Con excepción del tipo Ticket, todos los mensajes requieren que el cliente haya dado su consentimiento explícito para recibir comunicaciones por WhatsApp (whatsappOptIn = true). Si se intenta enviar un mensaje a un cliente sin opt-in, el sistema cancela el envío con el mensaje “El cliente no ha dado su consentimiento para recibir mensajes de WhatsApp”.

Activar el opt-in de un cliente

El opt-in se gestiona desde el perfil del cliente:

1. Abra el módulo Clientes y seleccione el cliente.
2. En la sección de datos de contacto, ubique el campo Teléfono WhatsApp.
3. Ingrese el número de WhatsApp en formato internacional si aún no está registrado.
4. Active el interruptor Acepta mensajes de WhatsApp.
5. Guarde los cambios.

ALTUM ERP registra automáticamente:

• whatsappOptIn: true.
• whatsappOptInDate: fecha y hora en que se activó el consentimiento.
• whatsappOptInMethod: 'MANUAL' (activado por un usuario interno).

Cada cambio de consentimiento queda registrado en la bitácora de auditoría del cliente con el usuario que realizó la modificación.

Desactivar el opt-in (opt-out)

Para registrar que el cliente ya no desea recibir mensajes:

1. Abra el perfil del cliente.
2. Desactive el interruptor Acepta mensajes de WhatsApp.
3. Guarde los cambios.

El sistema registra whatsappOptOutDate con la fecha de la baja. A partir de ese momento, ningún mensaje (excepto Ticket) podrá enviarse a ese cliente hasta que reactive el opt-in.

Flujo completo de envío

1. Usuario solicita envío (factura, cotización, ticket o recordatorio)
2. ALTUM ERP verifica que WhatsApp esté habilitado
3. Resuelve el número de teléfono de destino
4. Valida y convierte el número a formato E.164
5. Verifica el opt-in del cliente (excluye tipo Ticket)
6. Obtiene los datos del documento (folio, total, etc.)
7. Construye los parámetros de la plantilla
8. Registra el mensaje en estado PENDIENTE
9. Envía el mensaje a la API de Meta
10. Actualiza el estado a ENVIADO o FALLIDO
11. Emite evento de dominio (WhatsappMessageSent o WhatsappDeliveryFailed)

Reglas y validaciones

• El campo cooldownMinutes de la configuración establece el tiempo mínimo entre mensajes al mismo número. Esto aplica a todos los tipos de mensaje, incluyendo Ticket.
• Los mensajes se registran en la tabla WhatsappMessage con el ID del usuario que los solicitó, el tipo de documento y el ID del documento de origen (CFDI, venta, cotización o cliente).
• El número de teléfono se almacena en el registro del mensaje en formato E.164.
• No es posible enviar mensajes cuando la integración de WhatsApp está deshabilitada (enabled: false en la configuración).

Casos frecuentes

Un mensaje llega como “FALLIDO” aunque el cliente tiene opt-in. Verifique el errorCode en el historial de mensajes. Si es TEMPLATE_ERROR, revise que la plantilla correspondiente esté aprobada en Meta Business Suite y que el ID coincida con el registrado en ALTUM ERP.

El cliente reclama que no recibe los mensajes. Confirme que el número registrado en ALTUM ERP es correcto en formato internacional. También verifique que el cliente no haya bloqueado el número de su negocio en WhatsApp.

Necesito registrar el consentimiento de muchos clientes a la vez. Actualmente el opt-in se activa de forma individual desde cada perfil de cliente. Para actualizaciones masivas, consulte con soporte técnico la posibilidad de usar la API de ALTUM ERP.