Configuración de callbacks

La configuración de callbacks se utiliza para configurar las direcciones de callback de su sistema empresarial con el fin de recibir en tiempo real los eventos "Message Status" y "Message Response" enviados (push) por el servicio de SMS de EngageLab. Mediante el uso de callbacks, se puede automatizar el seguimiento de mensajes, implementar estrategias de reintento, activar alertas del sistema y mejorar la eficiencia del procesamiento de mensajes y la inteligencia del sistema.

• Message Status: Se refiere a los cambios de estado de mensajes SMS individuales durante varias etapas, como el envío, la entrega, la lectura y la verificación.
• Message Response: Se refiere al contenido y a los eventos de los mensajes respondidos por el usuario (uplink).

Lista de callbacks

La página de lista de callbacks muestra toda la información de callbacks configurada y su estado, lo que permite una gestión y un mantenimiento unificados.

• Barra de búsqueda: Admite el filtrado en tiempo real por descripción del callback para localizar rápidamente los callbacks de destino.
• Configurar callback: Hacer clic en el botón para acceder al proceso de configuración de un nuevo callback, lo que permite ampliar de forma flexible los requisitos de callback.

Descripciones de campos

Configurar callback

Hacer clic en el botón [Configurar callback] en la esquina superior derecha para acceder a la página.

Tal y como se muestra en la imagen anterior, completar los campos como "Descripción del callback", "URL de callback", "Nombre de usuario", "Authorization", "Eventos de callback" y "Message Response".

• Seleccionar los eventos de callback para enviar (push) información a la dirección de callback configurada cuando se produzcan los eventos seleccionados.
• Hacer clic en las opciones de estado de mensaje y respuesta de mensaje a la derecha para ver los ejemplos correspondientes.

Proceso de configuración

Al configurar la dirección de callback, el sistema de SMS de EngageLab enviará una solicitud HTTP POST a la dirección especificada. El servicio del desarrollador correspondiente a esta dirección debe responder con un código de estado HTTP 200 en un plazo de 3 segundos; de lo contrario, el sistema considerará que la dirección no es válida.

• El servicio del desarrollador solo debe responder con un código de estado HTTP 200, sin devolver un cuerpo de respuesta.

Ejemplo de solicitud

Suponiendo que la dirección de callback configurada es https://example.engagelabSMS.callback.com, el sistema enviará el siguiente payload vacío a la dirección. Se representa mediante el comando curl:

              
              curl -X POST https://example.engagelabSMS.callback.com -d ''

            

Ejemplo de respuesta

El servicio del desarrollador correspondiente a la dirección de callback solo debe responder con un código de estado HTTP 200, tal como se muestra a continuación:

              
              HTTP/1.1 200 OK
Content-Length: 0

            

Configuración de callbacks

• Configuración de nombre de usuario
  Este es un paso opcional. Si se establece un nombre de usuario, también se debe proporcionar una clave secreta.

  Para verificar que el origen del mensaje es EngageLab, se puede optar por autenticar el origen de los datos POST.

  Tras configurar el nombre de usuario y la clave secreta, los datos enviados por EngageLab incluirán un encabezado HTTP: X-CALLBACK-ID.
  El valor de X-CALLBACK-ID es:
  timestamp={timestamp};nonce={nonce};username={username};signature={signature}

  Ejemplo:

  X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b

                
                X-CALLBACK-ID: timestamp=1681991058;nonce=123123123123;username=test;signature=59682d71e2aa2747252e4e62c15f6f241ddecc8ff08999eda7e0c4451207a16b
  
              

  Este bloque de código se muestra en una ventana flotante
  • timestamp: Marca de tiempo del mensaje de callback (formato estándar).
  • nonce: Un número aleatorio.
  • signature: Información de firma, calculada como:
    signature=HMAC-SHA256(secret, timestamp+nonce+username)

  A continuación se muestra un ejemplo de código Python para calcular signature:

  import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg='{}{}{}'.format(timestamp, nonce, username).encode(), digestmod=hashlib.sha256 ).hexdigest()

                
                import hashlib, hmac
  
  def verify(username, secret, timestamp, nonce, signature):
      return signature == hmac.new(
          key=secret.encode(),
          msg='{}{}{}'.format(timestamp, nonce, username).encode(),
          digestmod=hashlib.sha256
      ).hexdigest()
  
              

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

• Configuración de Authorization
  Este es un paso opcional. Si su dirección de callback requiere autenticación para las solicitudes de EngageLab, proporcionar aquí la información de autenticación. EngageLab incluirá este encabezado Authorization en sus solicitudes.

Cuerpo de la solicitud de callback

Cuando se active un evento de callback, el sistema de SMS de EngageLab enviará datos a la dirección de callback.

Ejemplo de solicitud de "Message Status"

Message Status:

• plan: Planificado para enviar.
• sent: Enviado correctamente.
• sent_failed: Error de envío.
• delivered: Entregado correctamente.
• delivered_failed: Error de entrega.

              
              {
    "total": 2,
    "rows": [
        {
            "message_id": "1742442805608914944",
            "to": "+8615989574757",
            "server": "SMS",
            "channel": "SMS",
            "itime": 1704265712,
            "status": {
                "message_status": "plan",
                "status_data": {
                    "msg_time": 1704265712,
                    "message_id": "1742442805608914944",
                    "template_key": "auto_create_templateu25az170295320745",
                    "business_id": "100917676394736"
                },
                "error_code": 0
            }
        },
        {
            "message_id": "1742442805608914944",
            "to": "+8615989574757",
            "server": "SMS",
            "channel": "SMS",
            "itime": 1704265712,
            "status": {
                "message_status": "sent_failed",
                "status_data": {
                    "msg_time": 1704265712,
                    "message_id": "1742442805608914944",
                    "template_key": "auto_create_templateu25az170295320745",
                    "business_id": "100917676394736"
                },
                "error_code": 5001,
                "error_detail": {
                    "message": "sender config is invalid"
                }
            }
        }
    ]
}

            

Ejemplo de solicitud de "Message Response"

Event:

• uplink_message: Mensaje entrante (uplink).

              
              {
    "total": 1,
    "rows": [
        {
            "server": "SMS",
            "itime": 1741083306,
            "message_id": "0",
            "business_id": "0",
            "response": {
                "event": "uplink_message",
                "response_data": {
                    "message_sid": "SM1234567890",
                    "account_sid": "AC1234567890",
                    "from": "+1234567890",
                    "to": "+0987654321",
                    "body": "Hello, it's time to struggle!"
                }
            }
        }
    ]
}