Guía de integración de API de mensajería: REST, SMPP y webhooks

Esta guía está dirigida a desarrolladores backend, arquitectos de soluciones y directores técnicos que integran una aplicación con un proveedor de mensajería para WhatsApp, SMS o email. Explica qué interfaz utilizar y cómo gestionar la autenticación, la idempotencia, los informes de entrega (DLR), los reintentos, los límites de frecuencia y las pruebas, con ejemplos ilustrativos de solicitudes y respuestas. Para sincronizar conversaciones con un CRM, consulte la guía complementaria sobre cómo conectar un CRM mediante webhooks.

¿Qué interfaz debe usar: REST, SMPP o webhooks?

Use REST para enviar, webhooks para recibir y SMPP solo para SMS de gran volumen cuando ya opera con SMPP. Son interfaces complementarias y no competidoras: la mayoría de las integraciones combinan llamadas REST de salida con webhooks de entrada.

Las sesiones SMPP (Short Message Peer-to-Peer) comienzan con un bind (transmitter, receiver o transceiver), envían mensajes con submit_sm, reciben informes de entrega (DLR) y SMS entrantes mediante deliver_sm y se mantienen activas con enquire_link. Es eficiente, pero operativamente más pesado que HTTPS.

¿Cómo debe autenticarse?

Use el método más robusto que ofrezca el proveedor, mantenga los secretos fuera del código y autentique ambos sentidos.

• Llamadas salientes: claves de API o tokens de portador OAuth 2.0 enviados en la cabecera Authorization sobre TLS. Guárdelos en un gestor de secretos y rótelos con regularidad y tras cualquier cambio de personal.
• SMPP: identificador de sistema y contraseña en el bind, normalmente restringidos a direcciones IP autorizadas y, cuando se admita, sobre TLS.
• Webhooks entrantes: verifique una firma en cada evento. Meta firma las cargas útiles de los webhooks de la API en la nube de WhatsApp con una firma HMAC-SHA256 en la cabecera X-Hub-Signature-256, calculada con el secreto de su aplicación; los proveedores suelen ofrecer un esquema similar. Calcule la firma sobre el cuerpo sin procesar antes de analizarlo.

Use credenciales distintas por entorno para que una clave de prueba filtrada no pueda enviar tráfico de producción.

¿Cómo enviar un mensaje de forma segura?

Envíe a través de una cola, incluya una clave de idempotencia y trate la respuesta como «aceptado», no como «entregado».

Solicitud de envío de ejemplo

La estructura siguiente es pseudo-JSON a modo ilustrativo, no la API de un proveedor concreto.

POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: 7f3c9a2e-order-55821-shipped

{
  "channel": "whatsapp",
  "to": "+9715XXXXXXXX",
  "template": {
    "name": "order_shipped",
    "language": "ar",
    "variables": ["Layla", "55821", "15 March"]
  },
  "client_reference": "order-55821",
  "callback_url": "https://api.example.com/webhooks/messaging"
}

Respuesta de ejemplo

202 Accepted

{
  "message_id": "msg_01HZX...",
  "status": "accepted",
  "client_reference": "order-55821",
  "created_at": "2026-10-09T12:00:00Z"
}

Guarde de inmediato message_id junto a su propia referencia. Todo lo que ocurra después llega de forma asíncrona.

¿Por qué importa la idempotencia?

Porque las redes agotan el tiempo de espera cuando el servidor ya ha actuado. Si su solicitud de envío caduca y reintenta a ciegas, el cliente puede recibir dos OTP o dos avisos de envío. Una clave de idempotencia permite al servidor reconocer el reintento y devolver el resultado original.

Reglas que funcionan:

1. Derive la clave del evento de negocio (por ejemplo, el ID de pedido más el tipo de evento), no de un valor aleatorio en cada intento.
2. Reutilice la misma clave en cada reintento del mismo envío.
3. Mantenga las claves el tiempo suficiente para cubrir su ventana de reintentos.
4. Si el proveedor no admite claves, elimine duplicados por su cuenta antes de enviar.

El borrador de estándar de la IETF para la cabecera Idempotency-Key normaliza este patrón en las API HTTP; las implementaciones de los proveedores varían, así que lea su documentación.

¿Cómo funcionan los informes de entrega (DLR)?

El estado de entrega llega más tarde en forma de eventos: mediante webhooks en WhatsApp y en la mayoría de las API REST, y mediante informes de entrega (deliver_sm) en SMPP. El significado de los estados varía según el canal; nuestra guía sobre el estado de entrega de los mensajes explica cada uno.

Webhook de estado de ejemplo

POST /webhooks/messaging
X-Signature: sha256=<hmac>

{
  "event_id": "evt_9c1...",
  "type": "message.status",
  "message_id": "msg_01HZX...",
  "client_reference": "order-55821",
  "status": "delivered",
  "timestamp": "2026-10-09T12:00:04Z",
  "error": null
}

Trate los eventos de estado de forma defensiva:

• Elimine duplicados por event_id, o por ID de mensaje más estado.
• No retroceda nunca un mensaje de «leído» a «entregado» cuando los eventos lleguen desordenados.
• Responda con 2xx rápidamente y procese después desde una cola.
• Registre los códigos de error de los mensajes fallidos y decida cuáles admiten reintento.
• Cuente con lagunas: algunas rutas de SMS devuelven informes de entrega limitados, y el estado de lectura depende del canal y de los ajustes del usuario.

¿Cómo gestionar los reintentos y los límites de frecuencia?

Reintente solo lo que pueda tener éxito, espacie los reintentos de forma exponencial con jitter y respete las señales del servidor.

La RFC 9110 define la cabecera Retry-After, que puede contener segundos o una fecha. Coloque un limitador de frecuencia del lado del cliente antes de sus envíos para mantenerse por debajo de los límites documentados del proveedor en lugar de descubrirlos mediante errores. WhatsApp también aplica límites de Meta al número de clientes únicos a los que puede escribir, descritos en límites de mensajería y calificación de calidad.

¿Cómo probar antes de pasar a producción?

Pruebe las rutas de fallo, no solo el caso ideal.

Lista de verificación de preproducción

1. Envíe cada plantilla con valores de longitud real, incluido texto en árabe.
2. Fuerce un tiempo de espera agotado y confirme que el reintento no genera duplicados.
3. Envíe a un número no válido y confirme que el error se gestiona sin reintento.
4. Reproduzca un webhook dos veces y desordenado; confirme que queda un único estado final.
5. Envíe un webhook con una firma incorrecta; confirme que se rechaza.
6. Provoque 429 con una prueba de carga contra el entorno de pruebas, si se permite.
7. Rote una clave de API y confirme que no hay interrupción.
8. Compruebe que los registros contienen ID de mensaje pero no el cuerpo completo de los mensajes ni códigos OTP.
9. Realice un pequeño piloto en producción con números internos en cada canal.

Los entornos de pruebas rara vez reproducen con exactitud el comportamiento de los operadores y de Meta, así que mantenga la supervisión durante las primeras semanas de producción.

Ejemplo práctico: un servicio de OTP y notificaciones de pedidos

«Qafilah Logistics» (sintética), una empresa de paquetería de Arabia Saudí, envía avisos de pedidos por WhatsApp con SMS de respaldo y OTP de autenticación.

• Arquitectura: los eventos de pedido van a una cola; un worker de envío llama a la API REST con una clave de idempotencia shipment-id:event.
• Respaldo: si WhatsApp devuelve un estado fallido para un usuario sin WhatsApp, el worker envía un SMS con una clave nueva, shipment-id:event:sms.
• OTP: los códigos caducan pronto, por lo que los envíos de OTP no se reintentan pasada la ventana de caducidad; el usuario solicita un código nuevo. Consulte la guía de mensajes de autenticación OTP.
• Acuses: un receptor de webhooks verifica las firmas, elimina duplicados y actualiza una tabla de estados que nunca retrocede.
• Límites: un limitador de tipo token bucket fija la frecuencia de envío por canal por debajo de los límites documentados.

¿Cuáles son los errores de integración más habituales?

• Tratar «aceptado» como «entregado».
• Reintentar con una clave de idempotencia nueva en cada intento.
• Hacer un procesamiento pesado dentro de la solicitud del webhook.
• Omitir la verificación de firma de los webhooks.
• Reintentar en bucle los errores de validación 4xx.
• Registrar códigos OTP y el contenido completo de los mensajes.
• Usar credenciales de producción en entornos de prueba.

Cómo ayuda OmniChannels.ai

OmniChannels.ai, con la tecnología de BroadNet Technologies, ofrece una API REST/JSON documentada públicamente, con especificación OpenAPI 3.1 y un SDK de TypeScript, que cubre SMS, WhatsApp, RCS, Messenger, Instagram, Telegram, email y notificaciones push, incluidas las plantillas de autenticación de WhatsApp con OTP one-tap, zero-tap y copia de código. Los webhooks notifican los estados de entrega en un único formato normalizado, SMPP 3.4 sobre TLS atiende el SMS de gran volumen y un servidor MCP conecta agentes de IA. Los informes de entrega, con filtros y exportación a CSV, le ayudan a conciliar lo que envió su integración. Empiece por la documentación para desarrolladores y la guía de inicio rápido.