Logo Site EngageLab Mark Colored TransparentDocumentación
SMS
Server Center
DocumentaciónReferencia de API
Buscar
Iniciar sesión
Referencia de API/Referencia de eventos de callback
Referencia de APIReferencia de eventos de callback...

Referencia de eventos de callback

Última actualización：hace 5 días

Configuración y verificación de la dirección de callback

Tras configurar la dirección de callback, EngageLab SMS envía automáticamente una solicitud HTTP POST a dicha dirección para verificar la disponibilidad de la interfaz. Tu servicio debe devolver un código de estado HTTP 200 en un plazo de 3 segundos; de lo contrario, el sistema considerará que la dirección no está disponible.

Nota:
Para garantizar la correcta recepción de los datos de callback, añade 119.8.170.74 y 114.119.180.30 a la lista blanca del firewall de tu servidor.

Ejemplo de solicitud

Suponiendo que tu dirección de callback sea https://example.engagelabSMS.callback.com, el sistema enviará la siguiente solicitud:

curl -X POST https://example.engagelabSMS.callback.com -d '{}'
              
              curl -X POST https://example.engagelabSMS.callback.com -d '{}'
Este bloque de código se muestra en una ventana flotante

Requisitos de la respuesta

Tu servicio solo necesita devolver un código de estado HTTP 200, sin necesidad de devolver ningún contenido. Por ejemplo:

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
Este bloque de código se muestra en una ventana flotante

Nota:
La verificación de la dirección de callback solo evalúa el código de estado HTTP y no requiere devolver ningún contenido concreto en el mensaje. Asegúrate de que la interfaz de tu servicio pueda responder correctamente con un 200 en un plazo de 3 segundos.

Mecanismo de seguridad del callback

Para garantizar la seguridad de los datos de callback y la fiabilidad de su origen, EngageLab SMS admite varios métodos de verificación de seguridad.

Verificación de usuario y clave (opcional)

  • Configuración opcional. Si estableces un nombre de usuario, también debes establecer una clave.
  • Una vez configurado, EngageLab añade en la cabecera HTTP de cada solicitud de callback el campo X-CALLBACK-ID, con el siguiente formato:
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
Este bloque de código se muestra en una ventana flotante
  • Donde:
    • timestamp: marca de tiempo del envío del callback
    • nonce: número aleatorio
    • username: el nombre de usuario que configuraste
    • signature: información de la firma, calculada de la siguiente manera

Método de cálculo de la firma (ejemplo en Python)

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg=f'{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=f'{timestamp}{nonce}{username}'.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
Este bloque de código se muestra en una ventana flotante
  • El servidor puede usar el método anterior para verificar la legitimidad de la solicitud de callback.

Autenticación mediante Authorization (opcional)

  • Si tu interfaz de callback requiere autenticación (como Basic Auth, Bearer Token, etc.), puedes indicar la información de Authorization durante la configuración.
  • EngageLab incluirá automáticamente ese campo Authorization en la solicitud, lo que facilita que tu servicio verifique la identidad de la solicitud.

Descripción de los eventos de callback

Estado del mensaje

El estado del mensaje sirve para hacer seguimiento de los cambios de estado de cada mensaje a lo largo de su ciclo de vida. Permite conocer en tiempo real el avance de las distintas etapas del mensaje, como el envío, la entrega y la verificación, lo que facilita el análisis estadístico, el tratamiento de excepciones y la optimización de la experiencia de usuario.

Identificador del evento Descripción
plan El mensaje está programado para enviarse y entra en la cola de envío
target_valid El número de destino es válido
target_invalid El número de destino no es válido
sent El mensaje se envió correctamente
sent_failed El envío del mensaje falló
delivered El mensaje se entregó en el dispositivo del usuario
delivered_failed El mensaje se envió, pero no pudo entregarse en el dispositivo del usuario

Estructura de los datos de callback

Estructura externa

{ "total": 1, "rows": [ { // objeto ReportLifecycle } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // objeto ReportLifecycle
    }
  ]
}
Este bloque de código se muestra en una ventana flotante
Nombre del campo Tipo Descripción
total int Número de registros incluidos en este callback
rows array Array de datos de estado del ciclo de vida

Objeto ReportLifecycle

Nombre del campo Tipo Descripción
message_id string ID único del mensaje
to string Número del destinatario
server string Tipo de servicio (por ejemplo, SMS)
channel string Tipo de canal
itime int64 Marca de tiempo del callback (en segundos)
custom_args object Parámetros personalizados (se devuelven si se enviaron)
status object Objeto con los detalles del estado

Objeto status

Nombre del campo Tipo Descripción
message_status string Estado actual del mensaje (véase la tabla siguiente)
status_data object Objeto con los datos del estado
billing object Objeto con la información de facturación (se devuelve cuando hay facturación)
error_code int Código de error; 0 indica que no hay error
error_detail object Detalle del error (se devuelve cuando se produce un error)

Objeto status_data

Nombre del campo Tipo Descripción
msg_time int64 Marca de tiempo de creación del mensaje (en segundos)
message_id string ID del mensaje
current_send_channel string Nombre del canal de envío actual
template_key string Key de configuración de la plantilla
business_id string ID de negocio
plan_id string ID del plan

Objeto billing (se devuelve cuando hay facturación)

Nombre del campo Tipo Descripción
cost float64 Importe del coste
currency string Moneda, fija en "USD"

Por lo general, solo los mensajes en la etapa sent incluyen información de facturación.

Objeto error_detail (se devuelve cuando se produce un error)

Nombre del campo Tipo Descripción
message string Descripción del mensaje de error

Ejemplo: mensaje enviado correctamente

{ "total": 1, "rows": [ { "message_id": "123456789", "to": "+6598765432", "server": "sms", "channel": "sms", "itime": 1701234567, "custom_args": { "order_id": "ORDER123", "user_id": "USER456" }, "status": { "message_status": "sent", "status_data": { "msg_time": 1701234560, "message_id": "123456789", "current_send_channel": "CHANNEL_A", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "billing": { "cost": 0.005, "currency": "USD" }, "error_code": 0 } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "sent",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}
Este bloque de código se muestra en una ventana flotante

Ejemplo: fallo en el envío del mensaje

{ "total": 1, "rows": [ { "message_id": "123456790", "to": "+6598765433", "server": "sms", "channel": "sms", "itime": 1701234568, "status": { "message_status": "sent_fail", "status_data": { "msg_time": 1701234561, "message_id": "123456790", "current_send_channel": "CHANNEL_B", "template_key": "verify_code", "business_id": "1001", "plan_id": "7198765432109876543" }, "error_code": 4001, "error_detail": { "message": "Invalid phone number" } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001",
          "plan_id": "7198765432109876543"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number"
        }
      }
    }
  ]
}
Este bloque de código se muestra en una ventana flotante

Notificación de mensajes

La notificación de mensajes se refiere a eventos de negocio o alertas a nivel de sistema. Sirve para avisar a la parte de negocio sobre información importante como el estado de funcionamiento del servicio, el saldo o la revisión de plantillas, lo que facilita el tratamiento oportuno y la advertencia de riesgos.

Identificador del evento Descripción
template_audit_result Notificación del resultado de la revisión de una plantilla

Respuesta de mensajes

La respuesta de mensajes se refiere principalmente a los eventos de callback de respuesta durante la interacción con el usuario o con sistemas externos.

Identificador del evento Descripción
uplink_message Contenido del mensaje entrante (uplink) que el usuario responde, por ejemplo, mediante SMS

Ejemplo

{ "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!" } } } ] }
              
              {
    "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!"
                }
            }
        }
    ]
}
Este bloque de código se muestra en una ventana flotante

Eventos del sistema

Los eventos del sistema abarcan acciones relacionadas con la cuenta, las plantillas, las llamadas a la API, etc. Facilitan la monitorización, la auditoría y el tratamiento automatizado de operaciones clave como el inicio de sesión en la cuenta, los cambios de clave o las llamadas a la API.

Identificador del evento Descripción
account_login Notificación de operaciones relacionadas con el inicio de sesión en la cuenta
key_manage Notificación de operaciones relacionadas con el cambio y la gestión de claves
template_manage Notificación de operaciones de creación, modificación, eliminación, etc., de plantillas
api_call Notificación de operaciones relacionadas con las llamadas a la API

Estructura de los datos de callback

Estructura externa

{ "total": 1, "rows": [ { // objeto de evento del sistema } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // objeto de evento del sistema
    }
  ]
}
Este bloque de código se muestra en una ventana flotante
Campo Tipo Descripción
total int64 Número total de eventos incluidos en este callback
rows array Array de objetos de eventos del sistema

Objeto de evento del sistema

Campo Tipo Descripción
server string Fijo en "SMS"
itime int64 Marca de tiempo en que se produjo el evento (en segundos)
system_event object Contenido del evento del sistema

Objeto system_event

Campo Tipo Descripción
event string Tipo de evento
data object Datos del evento

Objeto data

Campo Tipo Descripción
business_id string ID de negocio
org_id string ID de la organización
operator object Información del operador

Objeto operator

Campo Tipo Descripción
email string Correo del operador (si lo hay)
api_key string API Key (si la hay)
ip_address string IP de la operación

Estructura de la solicitud

{ "total": 1, "rows": [ { "server": "SMS", "itime": 1694012345, "system_event": { "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "api_key": "api-xxxx", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "server": "SMS",
      "itime": 1694012345,
      "system_event": {
        "event": "account_login",
        "data": {
          "business_id": "123",
          "org_id": "org-abc",
          "operator": {
            "email": "foo@example.com",
            "api_key": "api-xxxx",
            "ip_address": "1.2.3.4"
          },
          "account_login": {
            "action": "login_success"
          }
        }
      }
    }
  ]
}
Este bloque de código se muestra en una ventana flotante

Evento de inicio de sesión en la cuenta

Campo Tipo Descripción
action string Inicio de sesión correcto/fallo de inicio de sesión/cierre de sesión
fail_reason string Motivo del fallo de inicio de sesión; solo se devuelve con login_failed

Ejemplo

{ "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } }
              
              {
  "event": "account_login",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "account_login": {
      "action": "login_success"
    }
  }
}
Este bloque de código se muestra en una ventana flotante

Evento de gestión de plantillas

Campo Tipo Descripción
action string Crear plantilla/actualizar plantilla/eliminar plantilla
template_id string ID de la plantilla
template_name string Nombre de la plantilla

Ejemplo

{ "event": "template_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "template_manage": { "action": "update template", "template_id": "tmpl-456", "template_name": "Verification Code" } } }
              
              {
  "event": "template_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "template_manage": {
      "action": "update template",
      "template_id": "tmpl-456",
      "template_name": "Verification Code"
    }
  }
}
Este bloque de código se muestra en una ventana flotante

Evento de gestión de claves

Campo Tipo Descripción
action string Crear clave/actualizar clave/eliminar clave/ver clave
api_key string API Key
description string Descripción (opcional)

Ejemplo

{ "event": "key_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "key_manage": { "action": "create", "api_key": "apikey-789", "description": "Nueva clave" } } }
              
              {
  "event": "key_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "key_manage": {
      "action": "create",
      "api_key": "apikey-789",
      "description": "Nueva clave"
    }
  }
}
Este bloque de código se muestra en una ventana flotante

Evento de llamada a la API

Campo Tipo Descripción
api_path string Ruta de la interfaz
method string Método HTTP

Ejemplo

{ "event": "api_call", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "api_key": "apikey-789", "ip_address": "1.2.3.4" }, "api_call": { "api_path": "/api/v1/messages/send", "method": "POST" } } }
              
              {
  "event": "api_call",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "api_key": "apikey-789",
      "ip_address": "1.2.3.4"
    },
    "api_call": {
      "api_path": "/api/v1/messages/send",
      "method": "POST"
    }
  }
}
Este bloque de código se muestra en una ventana flotante
Icon Solid Transparent White Qiyu
Contacto