Cómo recibir SMS usando la API SMPP

El protocolo Short Message Peer-to-Peer (SMPP) es un estándar de la industria diseñado para facilitar el intercambio de mensajes SMS entre Entidades de Mensajes Cortos Externas (ESMEs) y Centros de Servicio de Mensajes Cortos (SMSCs). Para desarrolladores y empresas que utilizan la API SMPP con Ozeki SMS Gateway como plataforma principal, entender las operaciones de bajo nivel del protocolo es esencial para construir soluciones de SMS robustas. Este artículo proporciona una guía completa sobre cómo recibir mensajes SMS usando la API SMPP, centrándose en las interacciones a nivel de protocolo y las Unidades de Datos de Protocolo (PDUs) específicas involucradas en la configuración, mantenimiento y uso de una conexión cliente de la API SMPP con Ozeki SMS Gateway.

Introducción a la API SMPP y Ozeki SMS Gateway

La API SMPP es ampliamente utilizada en la industria de telecomunicaciones por su eficiencia en el manejo de mensajes SMS masivos sobre conexiones TCP/IP. Ozeki SMS Gateway, un software SMPP versátil, actúa tanto como cliente como servidor SMPP, lo que lo convierte en una plataforma ideal para enviar y recibir mensajes SMS. Al implementar el protocolo SMPP (versiones 3.3 y 3.4, con soporte para 5.0 en Ozeki 10 SMS Gateway), Ozeki permite una conectividad sin problemas con SMSCs, soportando aplicaciones como campañas de marketing, autenticación de dos factores y sistemas de notificación. Este artículo se enfoca en recibir mensajes SMS, detallando las PDUs SMPP necesarias para la configuración de la conexión, mantenimiento y recepción de mensajes.

Entendiendo las PDUs SMPP

SMPP opera intercambiando Unidades de Datos de Protocolo (PDUs) entre el cliente SMPP (por ejemplo, Ozeki SMS Gateway) y el servidor SMPP (por ejemplo, un SMSC). Cada PDU es un mensaje estructurado que lleva instrucciones o datos específicos, como credenciales de autenticación, contenido de SMS o consultas de estado de conexión. Para recibir mensajes SMS usando la API SMPP, el cliente debe establecer una conexión, mantenerla y procesar los mensajes entrantes. Las PDUs clave involucradas son:

  • bind_transceiver: Establece una conexión para enviar y recibir SMS.
  • enquire_link: Mantiene la conexión verificando su estado.
  • deliver_sm: Entrega mensajes SMS entrantes desde el SMSC al cliente.
  • unbind: Termina la sesión SMPP.

A continuación, exploraremos cada PDU en detalle, incluyendo su estructura, configuración en Ozeki SMS Gateway y su rol en la recepción de mensajes SMS a través de la API SMPP.

Configuración de una conexión cliente de la API SMPP

Para recibir mensajes SMS, el primer paso es establecer una conexión cliente estable de la API SMPP con el SMSC. Ozeki SMS Gateway simplifica este proceso con su interfaz intuitiva, pero entender las operaciones subyacentes a nivel de protocolo es crucial para usuarios avanzados.

1. Configuración del cliente SMPP en Ozeki SMS Gateway

Para configurar una conexión cliente de la API SMPP en Ozeki SMS Gateway, sigue estos pasos:

  1. Iniciar sesión en la Consola de Administración: Accede a la interfaz web de Ozeki SMS Gateway usando la cuenta de administrador (usuario predeterminado: "admin").
  2. Añadir una nueva conexión: Navega al panel "Conexiones", haz clic en "Añadir nueva conexión" y selecciona "Cliente SMPP" en la sección "Conexiones SMS IP".
  3. Configurar ajustes SMPP: Proporciona los siguientes detalles, generalmente suministrados por tu proveedor de servicios SMS:
    • Nombre del Host: La dirección IP o nombre de host del SMSC (por ejemplo, "192.168.1.1").
    • Número de Puerto: El puerto TCP/IP para comunicación SMPP (el predeterminado es 9500, pero confirma con tu proveedor).
    • Usuario (ID del Sistema): Tu identificador de cuenta para el SMSC.
    • Contraseña: La contraseña asociada al ID del Sistema.
    • Versión SMPP: Selecciona v3.4 para soporte de transceptor (recomendado para enviar y recibir).
    • Tipo de Sistema: Opcional, a menudo "SMPP", según lo especificado por el proveedor.
    • Dirección del Remitente: El número de teléfono predeterminado para SMS salientes (por ejemplo, "+1234567890").
    • Rango de Direcciones: Opcional, usado para recibir mensajes de múltiples números.
  4. Modo de Enlace: Elige "Transceptor" para habilitar tanto el envío como la recepción de SMS sobre una sola conexión.
  5. Ajustes Avanzados: Habilita "Conectar automáticamente al inicio" para una reconexión sin problemas y marca "Enviar paquetes keepalive" para mantener la conexión.
  6. Habilitar Registro: En la pestaña "Avanzado", habilita "Registrar Eventos de Comunicación" para capturar PDUs SMPP para depuración.
  7. Guardar y Conectar: Haz clic en "OK" para guardar la configuración, luego haz clic en "Conectar" para iniciar la conexión.

Estos ajustes preparan Ozeki SMS Gateway para establecer una conexión de la API SMPP usando la PDU bind_transceiver.

2. La PDU bind_transceiver

La PDU bind_transceiver es la primera PDU enviada por el cliente SMPP para autenticar y establecer una conexión con el SMSC. Permite tanto enviar como recibir mensajes SMS sobre una sola conexión TCP/IP, lo que la hace ideal para la mayoría de las aplicaciones de la API SMPP.

Estructura de la PDU bind_transceiver

Longitud del Comando: 4 bytes (longitud total de la PDU)
ID del Comando: 0x00000009 (bind_transceiver)
Estado del Comando: 0x00000000 (establecido a 0 para solicitudes)
Número de Secuencia: Identificador único para la PDU
ID del Sistema: Nombre de usuario para autenticación (por ejemplo, "smppuser")
Contraseña: Contraseña para autenticación (por ejemplo, "password123")
Tipo de Sistema: Opcional, a menudo "SMPP"
Versión de la Interfaz: Versión SMPP (por ejemplo, 0x34 para v3.4)
Rango de Direcciones: Opcional, para recibir mensajes de números específicos

Ejemplo de PDU bind_transceiver (hexadecimal):

0000002F 00000009 00000000 00000001 736D70707573657200 70617373776F726431323300 534D505000 34 00

Explicación:

  • Longitud del Comando (0000002F): Longitud total de la PDU (47 bytes).
  • ID del Comando (00000009): Identifica la PDU como bind_transceiver.
  • Estado del Comando (00000000): Establecido a 0 para la solicitud.
  • Número de Secuencia (00000001): Un ID único para rastrear la PDU.
  • ID del Sistema (736D70707573657200): ASCII para "smppuser" seguido de un terminador nulo.
  • Contraseña (70617373776F726431323300): ASCII para "password123" seguido de un terminador nulo.
  • Tipo de Sistema (534D505000): ASCII para "SMPP" seguido de un terminador nulo.
  • Versión de la Interfaz (34): Indica SMPP v3.4.
  • Rango de Direcciones (00): Nulo, ya que es opcional.

Al recibir la PDU bind_transceiver, el SMSC valida las credenciales. Si es exitoso, responde con una PDU bind_transceiver_resp con un estado de comando 0x00000000, indicando una conexión exitosa. Ozeki SMS Gateway registra esta interacción, que puede verse en el registro "Eventos de Comunicación".

Manteniendo la conexión de la API SMPP

Una vez establecida la conexión, debe mantenerse activa para asegurar la recepción continua de SMS. El protocolo SMPP usa la PDU enquire_link para verificar el estado de la conexión y prevenir desconexiones por inactividad.

La PDU enquire_link

La PDU enquire_link es un mensaje ligero enviado periódicamente por el cliente SMPP al SMSC para confirmar que la conexión está activa. Esto es particularmente importante para mantener conexiones de larga duración, ya que servidores proxy o SMSCs pueden terminar conexiones inactivas.

Estructura de la PDU enquire_link

Longitud del Comando: 0x00000010 (16 bytes)
ID del Comando: 0x00000015 (enquire_link)
Estado del Comando: 0x00000000 (establecido a 0 para solicitudes)
Número de Secuencia: Identificador único para la PDU

Ejemplo de PDU enquire_link (hexadecimal):

00000010 00000015 00000000 00000002

Explicación:

  • Longitud del Comando (00000010): Longitud total (16 bytes).
  • ID del Comando (00000015): Identifica la PDU como enquire_link.
  • Estado del Comando (00000000): Establecido a 0 para la solicitud.
  • Número de Secuencia (00000002): Un ID único para rastrear la PDU.

El SMSC responde con una PDU enquire_link_resp, confirmando el estado de la conexión. En Ozeki SMS Gateway, habilitar la opción "Enviar paquetes keepalive" en la pestaña "Comunicación" asegura que las PDUs enquire_link se envíen automáticamente a intervalos regulares (por ejemplo, cada 30 segundos). Este ajuste es crítico para mantener una conexión estable de la API SMPP, especialmente al recibir mensajes SMS de manera intermitente.

Recibiendo mensajes SMS con la API SMPP

Una vez establecida y mantenida la conexión, el cliente de la API SMPP puede recibir mensajes SMS a través de la PDU deliver_sm. Esta PDU es enviada por el SMSC al cliente cuando hay un SMS entrante o un informe de entrega disponible.

La PDU deliver_sm

La PDU deliver_sm lleva el contenido de un mensaje SMS entrante o un informe de entrega. Para recibir SMS, la PDU contiene el número de teléfono del remitente, el número del destinatario (número virtual asignado por el proveedor) y el texto del mensaje.

Estructura de la PDU deliver_sm

Longitud del Comando: Variable (depende de la longitud del mensaje)
ID del Comando: 0x00000005 (deliver_sm)
Estado del Comando: 0x00000000 (establecido a 0 para solicitudes)
Número de Secuencia: Identificador único para la PDU
Tipo de Servicio: Opcional, a menudo nulo
TON de Dirección de Origen: Tipo de Número para el remitente
NPI de Dirección de Origen: Indicador de Plan de Numeración para el remitente
Dirección de Origen: Número de teléfono del remitente (por ejemplo, "+1234567890")
TON de Dirección de Destino: Tipo de Número para el destinatario
NPI de Dirección de Destino: Indicador de Plan de Numeración para el destinatario
Dirección de Destino: Número de teléfono del destinatario (por ejemplo, número virtual)
Clase ESM: Tipo de mensaje (por ejemplo, 0x04 para SMS)
Codificación de Datos: Codificación de caracteres (por ejemplo, 0x00 para GSM 7-bit)
Mensaje Corto: El texto del mensaje (hasta 160 caracteres para GSM)

Ejemplo de PDU deliver_sm (hexadecimal):

0000005F 00000005 00000000 00000003 00 01 01 2B3132333435363738393000 01 01 2B3938373635343332313000 00 00 00 00 00 48656C6C6F2C207468697320697320616E20534D5321

Explicación:

  • Longitud del Comando (0000005F): Longitud total (95 bytes).
  • ID del Comando (00000005): Identifica la PDU como deliver_sm.
  • Estado del Comando (00000000): Establecido a 0 para la solicitud.
  • Número de Secuencia (00000003): Un ID único para rastrear la PDU.
  • Tipo de Servicio (00): Nulo, ya que es opcional.
  • TON de Dirección de Origen (01): Número internacional.
  • NPI de Dirección de Origen (01): Plan de numeración ISDN/teléfono.
  • Dirección de Origen (2B3132333435363738393000): ASCII para "+1234567890".
  • TON de Dirección de Destino (01): Número internacional.
  • NPI de Dirección de Destino (01): Plan de numeración ISDN/teléfono.
  • Dirección de Destino (2B3938373635343332313000): ASCII para "+9876543210".
  • Clase ESM (00): Indica un SMS estándar.
  • Codificación de Datos (00): Codificación GSM 7-bit.
  • Mensaje Corto (48656C6C6F2C207468697320697320616E20534D5321): ASCII para "¡Hola, este es un SMS!".

Al recibir una PDU deliver_sm, Ozeki SMS Gateway procesa el mensaje y lo dirige a la aplicación o base de datos configurada. El cliente debe responder con una PDU deliver_sm_resp para confirmar la recepción, asegurando una entrega confiable. En Ozeki, esta respuesta se maneja automáticamente, y el mensaje se registra en el panel "Mensajes" o se almacena en la base de datos si está configurado.

Configuración de Ozeki SMS Gateway para recepción de SMS

Para asegurar que Ozeki SMS Gateway pueda recibir mensajes SMS:

  1. Configuración de Número Virtual: Colabora con tu proveedor de servicios SMS para asignar un número virtual (IMSI) para recibir SMS. Este número se especifica en el campo "Rango de Direcciones" durante la configuración.
  2. Integración con Base de Datos: Configura Ozeki para almacenar mensajes entrantes en una base de datos modificando la sentencia SQL SELECT en la configuración del "Usuario de Base de Datos" (por ejemplo, "SELECT id, sender, receiver, msg, msgtype FROM ozekimessagein").
  3. Registro: Habilita el registro de PDUs SMPP para monitorear las PDUs deliver_sm entrantes con fines de depuración.

Una vez configurado, los mensajes SMS entrantes se dirigen automáticamente a la aplicación o base de datos especificada, haciendo de Ozeki SMS Gateway una plataforma robusta para la recepción de SMS basada en la API SMPP.

Terminando la conexión de la API SMPP

Cuando la sesión de la API SMPP ya no sea necesaria, el cliente envía una PDU unbind para terminar la conexión de manera ordenada.

La PDU unbind

La PDU unbind indica al SMSC que cierre la sesión SMPP.

Estructura de la PDU unbind

Longitud del Comando: 0x00000010 (16 bytes)
ID del Comando: 0x00000006 (unbind)
Estado del Comando: 0x00000000 (establecido a 0 para solicitudes)
Número de Secuencia: Identificador único para la PDU

Ejemplo de PDU unbind (hexadecimal):

00000010 00000006 00000000 00000004

Explicación:

  • Longitud del Comando (00000010): Longitud total (16 bytes).
  • ID del Comando (00000006): Identifica la PDU como unbind.
  • Estado del Comando (00000000): Establecido a 0 para la solicitud.
  • Número de Secuencia (00000004): Un ID único para rastrear la PDU.

El SMSC responde con una PDU unbind_resp, confirmando la terminación de la sesión. En Ozeki SMS Gateway, puedes iniciar esto haciendo clic en "Desconectar" en el panel "Conexiones".

Mejores prácticas para usuarios de la API SMPP

Para optimizar tu implementación de la API SMPP con Ozeki SMS Gateway para recibir SMS:

  • Habilitar Paquetes Keepalive: Asegúrate de que la opción "Enviar paquetes keepalive" esté habilitada para mantener una conexión estable.
  • Monitorear Registros: Revisa regularmente los registros de PDUs SMPP para solucionar problemas con las PDUs bind_transceiver, enquire_link o deliver_sm.
  • Usar Modo Transceptor: Prefiere el modo transceptor para eficiencia, ya que soporta tanto enviar como recibir sobre una sola conexión.
  • Proteger Conexiones: Si tu proveedor lo soporta, usa SMPPS (SMPP sobre SSL/TLS) para comunicación cifrada.
  • Manejar Informes de Entrega: Configura Ozeki para procesar PDUs deliver_sm que contengan informes de entrega para rastrear el estado de los mensajes.

Conclusión

Recibir mensajes SMS usando la API SMPP con Ozeki SMS Gateway implica establecer una conexión con la PDU bind_transceiver, mantenerla con PDUs enquire_link y procesar mensajes entrantes a través de PDUs deliver_sm. Al entender estas PDUs y configurar Ozeki SMS Gateway apropiadamente, los desarrolladores pueden construir aplicaciones de SMS confiables y de alto rendimiento. La flexibilidad de la API SMPP y la robusta implementación de Ozeki la convierten en una excelente opción para negocios que requieren soluciones de SMS escalables. Para más detalles, consulta la documentación de Ozeki SMS Gateway o contacta a tu proveedor de servicios SMS para parámetros de configuración específicos.

More information