API SMPP

Información de la API

Este documento define el protocolo de comunicación SMPP para el servicio OTP de EngageLab y está diseñado para permitir una entrega de mensajes y una notificación de estado eficientes y fiables a través de conexiones TCP. La información de la API incluye la dirección IP, el número de puerto y los datos de autenticación necesarios para la conexión. Asegúrate de que la cuenta y la contraseña proporcionadas a través de canales autorizados estén configuradas correctamente.

Dirección SMPP

Dirección SMPP: otpsmpp.api.engagelab.cc

Obtén la siguiente información a través de un canal autorizado, como el soporte comercial o técnico:

• Puerto: { port }
• Cuenta: { system_id }
• Contraseña: { password }

Establecimiento de una conexión

Paquete del cliente

Después de establecer la conexión TCP, el primer paquete debe enviar el comando BindTransceiver (0x00000009) para la autenticación. Este paquete debe incluir los siguientes campos:

• system_id: la cuenta del sistema asignada al cliente, utilizada para identificarlo.
• password: la contraseña de acceso correspondiente a la cuenta del sistema, utilizada para la autenticación.

Respuesta del servidor

Respuesta correcta

• El servidor devuelve el comando BindTransceiverResp (0x80000009).
• El campo system_id se rellena con el mismo valor que el campo system_id recibido.

Respuesta fallida

• Si la autenticación falla, el servidor desconecta la conexión TCP y registra el motivo del fallo.

Envío de mensajes

Lógica del servidor

El envío de mensajes utiliza el comando SUBMIT_SM (0x00000004) para enviar una solicitud de entrega de mensajes. La lógica del servidor es la siguiente:

1. El servidor analiza el contenido de la solicitud y siempre utiliza el canal SMS para la entrega.
2. La entrega del mensaje es síncrona y el resultado se devuelve mediante el comando SUBMIT_SM_RESP (0x80000004).
3. El estado de la entrega se notifica mediante informes de entrega. Para obtener más información, consulta Informes de entrega.
4. Se recomienda utilizar la codificación UCS2 para admitir caracteres especiales e internacionalización.

Paquete del cliente

El cliente envía el comando SUBMIT_SM (0x00000004) para enviar un mensaje. El paquete debe incluir los siguientes campos:

1. service_type

   • Valor: MSG / CODE / MRKT
   • Valor predeterminado: MSG

2. source_addr

   • Puede dejarse vacío y actualmente no se utiliza en OTP.

3. destination_addr

   • El destino del mensaje, que debe estar en formato internacional de número de móvil (por ejemplo, +6598765432).

4. short_message

   • El contenido del mensaje utiliza formato JSON, como se muestra a continuación:
     { "id": "xxx", // ID de plantilla "language": "default", // Idioma utilizado; el valor predeterminado es default "code": "xx", // Código de verificación; se utiliza solo cuando service_type es CODE "params": { // Pares clave-valor personalizados "key1": "val1" // val debe estar en formato de cadena } }

                   
                   {
       "id": "xxx",           // ID de plantilla
       "language": "default", // Idioma utilizado; el valor predeterminado es default
       "code": "xx",          // Código de verificación; se utiliza solo cuando service_type es CODE
       "params": {            // Pares clave-valor personalizados
         "key1": "val1"       // val debe estar en formato de cadena
       }
     }
     
                 

     Este bloque de código se muestra en una ventana flotante

5. data_coding

   • Se recomienda utilizar la codificación UCS2 para garantizar que los caracteres especiales como {} se analicen correctamente.
   • Si se admite la transmisión directa de {}, puede utilizarse la codificación predeterminada (0x00).

6. status en la cabecera

   • Establecer en 0x00000000.

Respuesta del servidor

El servidor envía el comando SUBMIT_SM_RESP (0x80000004) como respuesta al resultado de la entrega del mensaje.

Respuesta correcta

• Valor del campo status en la cabecera: 0x00000000
• Campo MESSAGE_ID: ID del mensaje de respuesta, utilizado para correlacionar los informes de entrega.

Respuesta fallida

• El servidor rellena el campo status en la cabecera para indicar el motivo del fallo:

Informes de entrega

El servidor informa del estado de la entrega mediante el comando DELIVER_SM (0x00000005). Los campos relevantes son los siguientes:

1. service_type

   • Valor fijo: MSG

2. source_addr

   • Déjalo vacío.

3. destination_addr

   • Igual que destination_addr en el comando SUBMIT_SM.

4. data_coding

   • Método de codificación: valor predeterminado 0x00.

5. esm_class

   • Establecer en 0x00.

6. short_message

   • El informe de entrega se empaqueta utilizando el formato delivery receipt.

7. ReceiptedMessageID in TLV

   • ID del mensaje, utilizado para correlación e identificación.

8. MessageState in TLV

   • Estado del mensaje, valor del campo 0x0427.

Análisis del estado

En el campo short_message, el significado de los valores de stat es el siguiente:

Otras notas

Comandos no válidos

Para los comandos no válidos enviados por el cliente, el servidor devuelve el comando GENERIC_NACK (0x80000000) y registra los registros correspondientes. El servidor solo admite los siguientes comandos:

1. Comando EnquireLink (0x00000015)
2. Comando Unbind (0x00000006)
3. Comando SubmitSM (0x00000004)
4. Comando DeliverSMResp (0x80000005)
5. Comando BindTransceiver (0x00000009)

Keepalive

El cliente debe enviar el comando EnquireLink (0x00000015) una vez cada 30 segundos (tolerancia: ±5 segundos) para garantizar que la conexión permanezca activa.

Significado del estado de envío

Terminología

• SMPP: protocolo Short Message Peer-to-Peer, utilizado para el intercambio de mensajes con pasarelas SMS.
• SUBMIT_SM: comando SMPP para enviar mensajes SMS.
• DELIVER_SM: comando SMPP utilizado por el servidor para informar del estado de entrega del mensaje.

Si tienes alguna pregunta, ponte en contacto con el soporte técnico de OTP.