Los seis estados de un mensaje
Cada mensaje tiene un estado, legible con GET /v1/messages/{id} y enviado a su webhook.
- queued — aceptado por EnvoiSMS.ma, pendiente de salida.
- sent — entregado a la red; el operador aún no se ha pronunciado.
- delivered — el operador confirma la entrega en el teléfono.
- failed — el operador o la ruta rechazó el mensaje; error_code indica el motivo.
- undeliverable — no se puede contactar con el número (inexistente o dado de baja).
- unconfirmed — la red aceptó el mensaje pero nunca dio un veredicto en la ventana de informe; un DLR tardío sustituye este estado.
De dónde viene el acuse de recibo
El DLR (Delivery Report) lo emite el operador del destinatario, no nosotros: lo transmitimos tal cual. Un teléfono apagado o sin cobertura retrasa la entrega, y por tanto el DLR, a veces varias horas. «sent» no es un fallo: es una espera.
Leer un fallo: error_code
Un mensaje failed o undeliverable lleva un error_code corto y estable sobre el que su código puede decidir.
- DLR_<estado de red> — el fallo viene del informe del operador (por ejemplo DLR_REJECTD, DLR_EXPIRED, DLR_UNDELIV).
- GATEWAY_* — fallo en el enrutamiento de EnvoiSMS.ma, antes de llegar a la red.
- META_* — rechazo de WhatsApp, para los mensajes enviados por ese canal.
- Un código desconocido se trata como fallo definitivo: pueden aparecer valores nuevos.
Recibir los estados por webhook
Declare una URL y suscríbala a los eventos message.sent, message.delivered y message.failed. Cada llamada va firmada: verifique la cabecera X-EnvoiSMS-Signature-256 (HMAC-SHA256 del timestamp y del cuerpo) y rechace un timestamp de más de 5 minutos. Los metadatos enviados con el mensaje vuelven en el webhook, para enlazar el estado con su pedido o su usuario.
Qué se factura
Un mensaje fallido se reembolsa en cuanto tenemos la prueba de que la red no lo facturó; cuando falta esa prueba, nuestro equipo lo revisa en lugar de reembolsarlo a ciegas. Para un código OTP que genere usted mismo, añada metadata.purpose = "otp": ante un fallo definitivo hacia un número marroquí, el código aún válido (menos de 10 minutos) se reenvía una vez por otra ruta SMS, sin coste adicional.