🛡️ Confirmación de envío y manejo de errores en la API de HSM

¿Por qué te importa?

• Confiar en el estado de cada envío sin reconciliar manualmente con logs.

• Reintentar peticiones sin riesgo de duplicar mensajes en el WhatsApp del destinatario.

• Detectar fallos parciales (mensaje enviado, pero error interno posterior) con información clara y accionable.

Códigos HTTP que puedes recibir

Cuerpo de respuesta 207

{
  "status": 207,
  "message_id": "wamid.XXX",
  "ticket_id": "case123",
  "entry_id": 7,
  "warning": "hsm_sent_but_post_processing_failed",
  "stage": "update_entry_status"
}

• message_id: identificador del mensaje en WhatsApp. Confirma que el envío fue exitoso.

• ticket_id (si aplica): ticket asociado en Adereso.

• stage: etapa interna donde ocurrió el problema. Útil para soporte.

• warning: indicador estable que tu integración puede detectar.

Cómo se ve en una entrada de campaña

{
  "error_description": "Message was delivered to WhatsApp, but an internal post-processing error occurred.",
  "status_code": 207,
  "response": {
    "stage": "update_entry_status",
    "mid": "wamid.XXX",
    "case_id": "case123"
  }
}

Valores posibles de stage

Garantías que la API te entrega

• Sin duplicados al destinatario: si reintentas una entrada de campaña ya enviada, la API rechaza con 400 sin volver a llamar al proveedor de WhatsApp.

• Estado temprano de la entrada: en cuanto WhatsApp confirma la recepción, la entrada queda marcada como enviada con su mid y ticket_id. Esto sucede antes de cualquier paso posterior (apertura de bot, cierre de ticket).

• Los fallos posteriores no revierten el envío: cualquier problema posterior queda registrado en error_details con status_code = 207, nunca como una entrada en fallo.

• El código de respuesta refleja la entrega, no operaciones secundarias: actualizaciones de metadata, tags o template del ticket asociado se hacen best-effort. Si fallan, quedan en logs internos pero el código que recibes (200 o 207) sigue describiendo fielmente el resultado del envío.

• El 207 se entrega aunque el detalle no se persista: en el caso extremo de que la propia escritura del error_details falle (por ejemplo, blip transitorio de base de datos), la API igual responde 207 con message_id y ticket_id. Tu sistema no recibe un 500 engañoso cuando el mensaje sí llegó al destinatario.

Casos de uso

• Reconciliación automática: tu sistema puede sincronizar el estado leyendo status y error_details sin lógica especial para reintentos.

• Campañas masivas con intermitencias: la entrada queda registrada en cuanto WhatsApp confirma; cualquier inestabilidad posterior es transparente para tu reporte.

• Auditoría sin envíos duplicados: al recibir 207, puedes consultar el mid directamente con soporte sin reintentar.

Solución de problemas

Glosario

• HSM: plantilla pre-aprobada por Meta para iniciar conversaciones en WhatsApp.

• mid: identificador único del mensaje en WhatsApp (formato wamid.XXX).

• ticket_id: identificador del ticket de Adereso asociado al mensaje.

• entry_id: identificador de la entrada dentro de una campaña.

• Stage: etapa interna del procesamiento posterior al envío.

Resumen rápido

Árbol de decisión para integradores

1. ¿El código es 200? → Éxito total. Guardar message_id y ticket_id. No hacer nada más.

2. ¿El código es 207? → El mensaje llegó al destinatario. Guardar message_id y ticket_id. Registrar el warning y stage para auditoría. No reintentar.

3. ¿El código es 400 o 402? → Fallo definitivo. Revisar la petición o el estado de la cuenta. Reintentar sin cambios reproduce el error.

4. ¿El código es 500 o 503? → Reintentar es seguro. Usar backoff exponencial.

Gaps identificados en esta documentación