logoDocumentación
WebPush
Server Center
User GuideDeveloper GuideBest Practices
Buscar
Español
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
Indonesian
Deutsch
Français
Iniciar sesión
Developer Guide / REST API / Callback API

API de callback

Última actualización：hace alrededor de 1 año

Visión general

Los datos de estado de los mensajes se devuelven mediante callback al sistema empresarial de la empresa, y se puede realizar un análisis estadístico basado en la información.

Dirección de callback

La empresa debe configurar la dirección de callback para recibir los cambios de estado de los mensajes. Actualmente, no hay una interfaz web. Contactar con el personal técnico de Engagelab para configurar la dirección de callback.

Verificación de validez de la dirección de callback

Al configurar la dirección de callback en la administración del backend de Push, en Configuración de la aplicación, se enviará una solicitud POST con una cadena aleatoria de 8 caracteres como parámetro del cuerpo de la solicitud echostr. Se debe devolver el valor de echostr en el cuerpo de la respuesta, siguiendo el formato que se indica a continuación:

Cuerpo de la solicitud:

{ "echostr": "12345678" }
              
              {
    "echostr": "12345678"
}
Este bloque de código se muestra en una ventana flotante

Cuerpo de la respuesta:

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

Mecanismo de seguridad

Se utiliza para la autenticación del cliente, opcional.

Para garantizar que el origen de los mensajes sea Engagelab, se puede optar por autenticar el origen de los datos POST. Alternativamente, se pueden analizar directamente los datos POST sin autenticación.

El método de autenticación es el siguiente:

  • Configurar un nombre de usuario de callback (username) y un secreto de callback (secret) en la consola de Engagelab para la dirección de callback.

Recuperar X-CALLBACK-ID del encabezado de la solicitud, tal como se muestra en el ejemplo siguiente:

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

Aquí:

  • timestamp es la marca de tiempo del mensaje de callback (en formato estándar),
  • nonce es un número aleatorio,
  • signature es la información de firma.

El método de firma es el siguiente:

signature=HMAC-SHA256(secret, timestamp+nonce+username)
              
              signature=HMAC-SHA256(secret, timestamp+nonce+username)
Este bloque de código se muestra en una ventana flotante

Mecanismo de respuesta

Después de que el servicio del desarrollador reciba el callback de Engagelab, debe responder en un plazo de 3 segundos según los siguientes requisitos:

  • Recibido correctamente: el código de estado de la respuesta HTTP debe devolver 200 o 204 y no se requiere ningún mensaje de respuesta.
  • Error al recibir: el código de estado de la respuesta HTTP debe devolver 5XX o 4XX y un mensaje de respuesta. El formato es el siguiente:
{ "code": 2002, "message": "error" }
              
              {
    "code": 2002,
    "message": "error"
}
Este bloque de código se muestra en una ventana flotante
Campo Tipo Obligatorio/Opcional Descripción
code int Opcional Códigos de error
message string Opcional Detalles del error

Explicación de campos de callback

Cuerpo del mensaje

Nombre del campo Tipo Obligatorio/Opcional Descripción
total int Obligatorio El número de mensajes incluidos en este callback
rows array Obligatorio Una lista de información detallada sobre el cambio de estado del mensaje, que contiene los campos siguientes

Campos del array rows

Nombre del campo Tipo Obligatorio/Opcional Descripción
message_id string Obligatorio Identificador único del mensaje
from string Opcional Remitente; el valor predeterminado es appkey
to string Opcional Identificador del destinatario (p. ej., registrationID)
server string Obligatorio Nombre del servicio de mensajes; valores posibles: WebPush
channel string Obligatorio Canal del mensaje; valores posibles: EngageLab, Chrome, Firefox, Safari, Edge, Opera, Other
custom_args object Opcional Parámetros personalizados enviados durante la creación del mensaje; se devuelven tal cual
itime int Obligatorio Marca de tiempo real en la que se produjo el estado del mensaje; se puede utilizar con message_status para obtener la marca de tiempo de cada estado del mensaje
status object Obligatorio Información del estado del mensaje, que contiene los campos siguientes

Campos del objeto status

Nombre del campo Tipo Obligatorio/Opcional Descripción
message_status string Obligatorio Estado del mensaje; valores posibles: target_valid, sent, delivered, click, target_invalid, sent_failed, delivered_failed, no_click
status_data object Opcional Datos de estado personalizados, que contienen los campos siguientes
channel_message_id string Opcional ID del mensaje de canales de terceros
ntf_msg int Obligatorio Tipo de mensaje; valores posibles: 1: Notification, 2: Custom Message, 7: In-App Message
platform string Obligatorio Plataforma de push; valores posibles: b: Web
uid int Obligatorio UID del destinatario del mensaje push
app_version string Obligatorio Versión de la aplicación integrada con el SDK, obtenida mediante datos reportados por el SDK
channel string Obligatorio Canal de la aplicación integrada con el SDK, obtenido mediante datos reportados por el SDK
msg_time int Obligatorio Hora de entrega del mensaje; la hora en la que la solicitud de la API para enviar el mensaje se completa correctamente
time_zone string Obligatorio Zona horaria de la organización
loss_valid_type int Opcional Este campo no tiene significado real y no es necesario procesarlo
plan_user_total int Opcional Este campo no tiene significado real y no es necesario procesarlo
callback_type int Opcional Este campo no tiene significado real y no es necesario procesarlo
error_code int Opcional Código de error; se proporciona únicamente en caso de fallo
error_detail object Opcional Información detallada del error; se proporciona únicamente en caso de fallo e incluye los campos siguientes
message string Opcional Describe el motivo detallado del error; solo aplica para el canal FCM
loss object Opcional Información de pérdida, que contiene los campos siguientes
loss_source string Opcional Origen de la pérdida; valores posibles: EngageLab, Chrome, Firefox, Safari, Edge, Opera, Other
loss_step int Opcional Etapa de pérdida; valores posibles: 1: Plan Target → Valid Target, 2: Valid Target → Sent Quantity, 3: Sent Quantity → Delivered Quantity, 4: Delivered Quantity → Click Quantity

Valores de estado del mensaje

Valor de estado Significado Descripción
target_valid Destino válido Se considera válido si ha estado activo en los últimos 365 días
sent Enviado correctamente Enviado correctamente al servidor
delivered Entregado correctamente Entregado según el callback real
click El usuario hizo clic Clic del usuario informado por el SDK
target_invalid Destino no válido Se considera no válido según la etapa de pérdida 1, tal como se define
sent_failed Error de envío Se considera no válido según la etapa de pérdida 2, tal como se define
delivered_failed Error de entrega Se considera fallo según la etapa de pérdida 3, tal como se define
no_click Error de clic Se considera fallo según la etapa de pérdida 4, tal como se define; solo aplica a mensajes in-app

Fase de pérdida

  1. Destinos planificados → Destinos válidos
  2. Destinos válidos → Enviados
  3. Enviados → Entregados
  4. Entregados → Clics

Nota:

  1. Los clics y las entregas en algunos canales pueden estar duplicados; se puede realizar la desduplicación por cuenta propia.
  2. La cantidad de entrega y la cantidad de visualización no se reajustarán 5 días después de que la entrega sea correcta.
Icon Solid Transparent White Qiyu
Contacto