EngageLab

La capa de API admite funciones temporizadas y mantiene un objeto Schedule para la ejecución independiente de tareas.

Nota: Las tareas programadas creadas mediante la API solo se pueden recuperar, modificar o eliminar mediante llamadas a la API.

Autenticación

Para más detalles, se pueden consultar los métodos de autenticación en la visión general de la API REST.

Descripción de parámetros de Schedule

Cada tarea programada consta de cuatro secciones: name, enabled, trigger y push.

Parámetro	Tipo	Opcional	Descripción
name	String	No	El nombre de la tarea programada no debe superar los 255 bytes y debe estar compuesto por caracteres chinos, letras, números y guiones bajos.
enabled	Boolean	No	Indica el estado actual de la tarea; debe ser true al crear una tarea.
trigger	JSON Object	No	Las condiciones de activación y el momento de ejecución de la tarea programada. Actualmente se admiten tareas de una sola vez (`single`), tareas periódicas (`periodical`) y entrega inteligente (`intelligent`). Para más detalles, consultar la descripción de single.
push	JSON Object	No	La información de contenido del push; ver los campos en la documentación de AppPush.

Descripción de single

Describe las condiciones de activación de la tarea programada, incluido el momento de activación y el tipo de tarea programada.

Parámetro	Tipo	Opcional	Descripción
time	String	No	La hora de activación de la tarea programada, en el formato de hora estándar "yyyy-mm-dd hh:mm:ss", por ejemplo, "2014-02-15 13:16:59". No se aceptan formatos incompletos como "2014-2-15 13:16:59" o "2014-12-15 13:16". La hora más tardía de una tarea programada no puede superar un año.
zone_type	Int	No	Indica el tipo de tarea programada: 1 para activación según la zona horaria configurada en el sitio principal, 2 para activación según la zona horaria del terminal del usuario.

Descripción de periodical

Parámetro	Tipo	Opcional	Descripción
start	String	No	La hora de inicio de vigencia de la tarea periódica, estrictamente en el formato "yyyy-MM-dd HH:mm:ss", y debe estar en formato de 24 horas.
end	String	No	La hora de expiración de la tarea periódica, en el mismo formato que el anterior. El intervalo máximo de una tarea periódica no debe superar un año.
time	String	No	La hora específica en la que se activa la tarea periódica, estrictamente en el formato "HH:mm:ss", y debe estar en formato de 24 horas.
time_unit	String	No	La unidad de tiempo mínima para la ejecución de la tarea periódica, con tres opciones: "day", "week" y "month". No distingue entre mayúsculas y minúsculas.
point	String	No	Una lista correspondiente a time_unit: consultar la tabla siguiente.
zone_type	Int	No	Indica el tipo de tarea programada: 1 para activación según la zona horaria configurada en el sitio principal, 2 para activación según la zona horaria del terminal del usuario.

Información detallada sobre el parámetro point:

time_unit	point	Descripción
day	NULL	Cuando time_unit es day, point no aplica.
week	"MON","TUE","WED","THU","FRI","SAT","SUN"	Para week, point puede ser uno o varios días que indican cuándo se activa; no distingue entre mayúsculas y minúsculas.
month	"01","02","03" ... "31"	Para month, point corresponde a fechas válidas del mes; no se activará en fechas no válidas, como el 31 o el 30 de febrero.

Descripción de intelligent

Parámetro	Tipo	Opcional	Significado
backup_time	String	Obligatorio	La entrega inteligente es una función exclusiva de EngageLab, diseñada para optimizar la tasa de clics de las notificaciones. Cada vez que un usuario accede a su servicio a través de un sitio web o una app móvil con el SDK de EngageLab instalado, se rastrea la hora de actividad más reciente del usuario. El sistema registra estos datos y, en función de los hábitos de uso previos del usuario, envía notificaciones a cada usuario en el momento adecuado según la zona horaria del terminal de cada usuario. Para los usuarios sin datos históricos de actividad, se debe elegir entre enviarlo inmediatamente o especificar una hora de envío (según la zona horaria del usuario final). Para envío inmediato: now Para envío programado: el formato debe ser estrictamente "yyyy-MM-dd HH:mm:ss", y la hora debe estar en formato de 24 horas.

Creación de una tarea programada

Endpoint

POST v4/schedules

Limitaciones

El número total de tareas programadas efectivas (aún no expiradas) está limitado de forma predeterminada a 1000. La creación de nuevas tareas fallará si se supera este número.
No hay restricciones sobre el intervalo máximo de una tarea programada, pero se recomienda no superar 1 año.
El nombre de la tarea programada no puede superar 255 caracteres y solo puede contener números, letras, guiones bajos y caracteres chinos.

Ejemplo de solicitud

Encabezados de la solicitud

POST /v4/schedules Authorization: Basic (base64 auth string) Content-Type: application/json Accept: application/json

              
              POST /v4/schedules
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json

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

Explicación de los datos de la solicitud

zone_type debe completarse con los valores de campo especificados (1 o 2); de lo contrario, el push se realizará según la zona horaria del servidor.
Cuando una tarea programada se crea inicialmente, el campo enabled debe ser true. La creación de una tarea con enabled: false fallará.
push debe ser una acción de push válida y correcta; de lo contrario, la creación fallará.

Ejemplo de respuesta

Respuesta correcta

{ "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6", "name": "Timed Task Name" }

              
              {
    "schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
    "name": "Timed Task Name"
}

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

Obtener los detalles de una tarea programada

Ejemplo de respuesta

[{ "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512", "name": "Ejemplo de envío programado", "enabled": true, "trigger": {...}, "push": {...} }]

              
              [{
    "schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
    "name": "Ejemplo de envío programado",
    "enabled": true,
    "trigger": {...},
    "push": {...}
}]

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

Obtener todos los ID de mensajes de la tarea programada

El formato de los datos de retorno se actualizó después de que la función de tareas programadas repetidas se publicara el 22 de febrero de 2024, añadiendo los datos MsgIds devueltos para sustituir a los msgids antiguos. Se debe asegurar que el código sea compatible.

Códigos de error

Código	HTTP	Descripción	Mensaje de error	Explicación detallada
28100	400	Parámetro no válido	The schedule-task is invalid	Los parámetros son incorrectos o no válidos. El push supera el límite. El cuerpo del parámetro es demasiado largo.
28203	503	Error interno del servidor; reintentar más tarde	Execute action timeout, please try later again	Error de comunicación con el schedule-server.

API de tareas programadas

Autenticación

Descripción de parámetros de Schedule

Descripción de single

Descripción de periodical

Descripción de intelligent

Creación de una tarea programada

Endpoint

Limitaciones

Ejemplo de solicitud

Ejemplo de respuesta

Obtener los detalles de una tarea programada

Ejemplo de respuesta

Obtener todos los ID de mensajes de la tarea programada

Códigos de error