Scheduled Tasks API
Einführung
Die Scheduled Tasks API bietet eine umfassende Zeitplanungsfunktion, mit der Sie Aufgaben automatisiert und effizient verwalten können. Dieses eigenständige Modul zur Aufgabenverwaltung ermöglicht es, sogenannte Schedule-Objekte zu erstellen, zu aktualisieren, abzufragen und zu löschen.
Hinweis: Nutzen Sie die bereitgestellten API-Endpunkte, um Informationen zu Zeitplänen abzurufen, zu aktualisieren oder zu entfernen.
Weitere Details zur Authentifizierung finden Sie unter Authentifizierungsmethode.
Beschreibung der Schedule-Parameter
Jede geplante Aufgabe (Scheduled Task) umfasst die vier Felder: name, enabled, trigger und push.
| Schlüsselwort | Typ | Optional | Beschreibung |
|---|---|---|---|
| name | string | erforderlich | Name der geplanten Aufgabe. Darf maximal 255 Bytes umfassen und kann chinesische Zeichen, Buchstaben, Zahlen sowie Unterstriche enthalten. |
| enabled | bool | erforderlich | Gibt den aktuellen Status der Aufgabe an. Beim Erstellen einer Aufgabe muss dieser Wert auf true gesetzt werden. |
| trigger | JSON-Objekt | erforderlich | Definiert die Auslösebedingungen und Zeitpunkte für die geplante Aufgabe. Unterstützt aktuell einmalige Aufgaben (single), periodische Aufgaben (periodical) und intelligente Zustellung (intelligent). |
| push | JSON-Objekt | erforderlich | Enthält Informationen zum Push-Inhalt. |
Beschreibung „Single“
Definiert die Auslösebedingungen für eine einmalige geplante Aufgabe, einschließlich Zeitpunkt und Typ.
| Parameter | Typ | Optional | Beschreibung |
|---|---|---|---|
| time | String | Nein | Der Auslösezeitpunkt der Aufgabe im Format „yyyy-MM-dd HH:mm:ss“, z. B. „2014-02-15 13:16:59“. Unvollständige Formate wie „2014-2-15 13:16:59“ oder „2014-12-15 13:16“ sind nicht zulässig. Der Zeitpunkt darf maximal ein Jahr in der Zukunft liegen. |
| zone_type | Int | Nein | Typ der geplanten Aufgabe: 1 = Auslösung nach Zeitzone der Hauptseite, 2 = Auslösung nach Zeitzone des Endgeräts der Nutzer:innen. |
Beschreibung „Periodical“
Definiert die Parameter für periodisch wiederkehrende Aufgaben.
| Parameter | Typ | Optional | Beschreibung |
|---|---|---|---|
| start | String | Nein | Startzeitpunkt der periodischen Aufgabe, im Format „yyyy-MM-dd HH:mm:ss“ (24-Stunden-Format). |
| end | String | Nein | Endzeitpunkt der periodischen Aufgabe, gleiches Format wie oben. Die maximale Zeitspanne sollte ein Jahr nicht überschreiten. |
| time | String | Nein | Exakte Uhrzeit, zu der die Aufgabe ausgelöst wird, im Format „HH:mm:ss“ (24-Stunden-Format). |
| time_unit | String | Nein | Kleinste Zeiteinheit für die Ausführung: „day“, „week“ oder „month“. Groß-/Kleinschreibung wird ignoriert. |
| point | String | Nein | Eine Liste entsprechend der time_unit, siehe untenstehende Tabelle. |
| zone_type | Int | Nein | Typ der geplanten Aufgabe: 1 = Auslösung nach Zeitzone der Hauptseite, 2 = Auslösung nach Zeitzone des Endgeräts der Nutzer:innen. |
Detailinformationen zum Parameter „point“:
| time_unit | point | Beschreibung |
|---|---|---|
| day | NULL | Bei time_unit = day ist point nicht anwendbar. |
| week | "MON","TUE","WED","THU","FRI","SAT","SUN" | Bei week kann point ein oder mehrere Wochentage angeben, an denen ausgelöst werden soll (Groß-/Kleinschreibung wird ignoriert). |
| month | "01","02","03" ... "31" | Bei month entspricht point gültigen Kalendertagen des Monats. An ungültigen Tagen wie dem 31. oder 30. Februar erfolgt keine Auslösung. |
Beschreibung „Intelligent“
| Parameter | Typ | Optional | Bedeutung |
|---|---|---|---|
| backup_time | String | Erforderlich | Die intelligente Zustellung ist eine exklusive Funktion von EngageLab zur Optimierung der Klickrate von Benachrichtigungen. Jedes Mal, wenn Nutzer:innen Ihren Service über eine Website oder mobile App mit EngageLab SDK nutzen, wird die letzte Aktivitätszeit gespeichert. Das System sendet Benachrichtigungen basierend auf bisherigen Nutzungsgewohnheiten zu einem optimalen Zeitpunkt in der jeweiligen Zeitzone des Endgeräts. Für Nutzer:innen ohne aktive Verlaufsdaten kann die Benachrichtigung entweder sofort („now“) oder zu einem bestimmten Zeitpunkt (Format: „yyyy-MM-dd HH:mm:ss“, 24-Stunden-Format) gesendet werden. |
Geplante Aufgabe erstellen
API-Endpunkt
POST v4/schedules
Aufrufbeschränkungen
- Die Gesamtanzahl gültiger (nicht abgelaufener) geplanter Aufgaben beträgt standardmäßig 1.000. Wird diese Zahl überschritten, schlägt das Erstellen einer neuen Aufgabe fehl.
- Die maximale Zeitspanne einer Aufgabe ist unbegrenzt, empfohlen wird jedoch, ein Jahr nicht zu überschreiten.
Beispiel für einen Request-Header
POST /v4/schedules
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Beispiel für einen Request-Body
{
"name": "schedule push example",
"enabled": true,
"trigger": {
"single": {
"time": "2022-11-23 19:20:00",
"zone_type": 1
}
},
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform": "web",
"notification": {
"web": {
"alert": "welcome to engagelab",
"title": "welcome to engagelab",
"url": "https://www.engagelab.com/",
"extras": {
"key1": "value1"
}
}
},
"message": {},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args": {
"Engagelab": "push to you"
}
}
}
Hinweise zum Request-Body:
- zone_type ist ein Pflichtfeld und muss 1 oder 2 sein. Andernfalls erfolgt das Pushen nach der Zeitzone des Servers.
- Das Feld enabled muss beim Erstellen auf true gesetzt werden. Aufgaben mit enabled: false können nicht erstellt werden.
- Das push-Objekt muss eine gültige und zulässige Push-Aktion enthalten, sonst schlägt die Erstellung fehl.
Beispiel für eine erfolgreiche Rückgabe
HTTP/1.1 200 OK
Server: fasthttp
Date: Thu, 01 Dec 2022 07:17:45 GMT
Content-Type: application/json
Content-Length: 85
{
"schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
"name": "the schedule task name"
}
Fehlerhafte Antwort
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json; charset=utf-8
{
"error": {
"code": 28400,
"message": "error message"
}
}
Beispiel für eine periodische geplante Aufgabe
{
"name": "Timed Push Example_periodical",
"enabled": true,
"trigger": {
"periodical": {
"start": "2024-01-01 00:00:00",
"end": "2024-02-10 00:00:00",
"time": "12:00:00",
"time_unit": "day",
"point": [],
"zone_type": 1
}
},
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform": "web",
"notification": {
"web": {
"alert": "welcome to engagelab",
"title": "welcome to engagelab",
"url": "https://www.engagelab.com/",
"extras": {
"key1": "value1"
}
}
},
"message": {},
"options": {
"time_to_live": 60
}
},
"request_id": "67890",
"custom_args": {
"Engagelab": "push to you"
}
}
}
Gültige geplante Aufgaben abrufen
Ruft die Liste aller aktuell gültigen (nicht abgelaufenen) geplanten Aufgaben ab.
API-Endpunkt
GET v4/schedules?page=
Beispiel für einen Request-Header
GET /v4/schedules?page=
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
- Gibt die detaillierte Liste der geplanten Aufgaben der angeforderten Seite zurück. Ohne Angabe einer Seite wird standardmäßig Seite 1 verwendet.
- Sortierung erfolgt nach Erstellungszeit.
- Ist die angeforderte Seitennummer größer als die Gesamtseitenanzahl, bleibt das schedules-Array leer.
- Pro Seite werden maximal 50 Aufgaben zurückgegeben.
Beispiel für eine erfolgreiche Rückgabe
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"total_count": 1000,
"total_pages": 5,
"page": 4,
"schedules": [
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "",
"enabled": true
}
// weitere Aufgaben
]
}
Details einer geplanten Aufgabe abrufen
Ruft die Details einer geplanten Aufgabe anhand der schedule_id ab.
API-Endpunkt
GET v4/schedules/{schedule_id}
Beispiel für einen Request-Header
GET /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Beispiel für eine erfolgreiche Rückgabe
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "the scheduled task example",
"enabled": true,
"trigger": {...},
"push": {...}
}]
- Existiert die schedule_id nicht, wird ein 404-Fehler zurückgegeben.
Alle Nachrichten-IDs einer geplanten Aufgabe abrufen
Ruft alle Nachrichten-IDs der aktuellen geplanten Aufgabe anhand der schedule_id ab.
API-Endpunkt
GET v4/schedules/{schedule_id}/msg-ids
Beispiel für einen Request-Header
GET /v4/schedules/{schedule_id}/msg-ids
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Beispiel für eine erfolgreiche Antwort
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"count": 1,
"MsgIds": [
"{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}",
"{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Kann kein Versandziel finden\"},\"needRetry\":false,\"ts\":1707278411611}"
]
}
- Das Feld ts gibt den Zeitstempel (in Millisekunden) der erfolgreichen Ausführung an.
- Das Rückgabeformat wurde am 22.02.2024 aktualisiert. Das Feld MsgIds ersetzt das bisherige msgids.
Geplante Aufgabe aktualisieren
Aktualisiert eine geplante Aufgabe anhand der angegebenen schedule_id.
API-Endpunkt
PUT v4/schedules/{schedule_id}
Beispiel für einen Request-Header
PUT /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Beispiel für einen vollständigen Update-Body
{
"name": "the scheduled task example",
"enabled": true,
"trigger": {
"single": {
"time": "2022-11-23 19:20:00",
"zone_type": 1
}
},
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform": "web",
"notification": {
"web": {
"alert": "welcome to engagelab",
"title": "welcome to engagelab",
"url": "https://www.engagelab.com/",
"extras": {
"key1": "value1"
}
}
},
"message": {},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args": {
"Engagelab": "push to you"
}
}
}
Hinweise:
- Eine abgelaufene Aufgabe kann nicht aktualisiert werden.
- Aufgaben, die nach Zeitzone des Endgeräts oder der Hauptseite ausgelöst werden, können nicht gegenseitig aktualisiert werden.
- Es können eines oder mehrere Felder aus ["name", "enabled", "trigger", "push"] aktualisiert werden. Der Update-Body muss jedoch immer vollständig ausgefüllt sein.
Fehlerhafte Aktualisierung: Es wird nur das Feld alert im push-Objekt aktualisiert
{
"push": {
"alert": "web scheduled task"
}
}
Korrekte Aktualisierung: Das push-Objekt ist vollständig
{
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform": "web scheduled task",
"notification": {
"web": {
"alert": "welcome to engagelab",
"title": "welcome to engagelab",
"url": "https://www.engagelab.com/",
"extras": {
"key1": "value1"
}
}
},
"message": {},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args": {
"Engagelab": "push to you"
}
}
}
- Das push-Objekt muss gültig und vollständig sein, sonst schlägt das Update fehl.
Beispiel für eine erfolgreiche Rückgabe
HTTP/1.0 200 CREATED
Content-Type: application/json
{
"name": "Timed push example",
"enabled": true,
"trigger": {
"single": {
"time": "2022-11-23 19:20:00",
"zone_type": 1
}
},
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform": "web",
"notification": {
"web": {
"alert": "welcome to engagelab",
"title": "welcome to engagelab",
"url": "https://www.engagelab.com/",
"extras": {
"key1": "value1"
}
}
},
"message": {},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args": {
"Engagelab": "push to you"
}
}
}
Fehlerhafte Antwort
- Ungültige schedule_id:
HTTP/1.0 404 Not Found
Content-Type: application/json
- Ungültige Update-Operation:
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
Geplante Aufgabe löschen
API-Endpunkt
DELETE v4/schedules/{schedule_id}
Hinweis: Die
schedule_idmuss einer bestehenden geplanten Aufgabe entsprechen. Ist sie ungültig oder nicht vorhanden, wird ein 404-Fehler zurückgegeben.
Beispiel für einen Request-Header
DELETE /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Beispiel für eine erfolgreiche Rückgabe
HTTP/1.0 200
Content-Type: application/json
Content-Length: 0
Fehlerhafte Antwort
HTTP/1.0 404 Not Found
Content-Type: application/json
Content-Length: 0
{
"error": {
"code": 28404,
"message": "error message"
}
}
Fehlercodes
| Code | HTTP | Beschreibung | Fehlermeldung | Ausführliche Erklärung |
|---|---|---|---|---|
| 28000 | 200 | Erfolgreiche Rückgabe | - | Erfolgsstatus |
| 28100 | 400 | Ungültiger Parameter | The schedule-task is invalid: section is invalid; has been at term; expired; request data is not JSON; update target task; delete target task; schedule request does not exist | |
| 28101 | 401 | Authentifizierung fehlgeschlagen | Basic authentication failed. | appkey und mastersecret stimmen nicht überein. |
| 28102 | 400 | Ungültiger Push-Parameter | push param is nil or invalid | Ungültiger Push-Parameter, spezifische Fehlermeldung wird zurückgegeben. |
| 28103 | 400 | Ungültiger Push-Zeitparameter | single time or trigger time format err | Ungültiger Push-Zeitparameter, spezifische Fehlermeldung wird zurückgegeben. |
| 28104 | 404 | Angeforderte geplante Aufgabe existiert nicht | Request schedule operation doesn't exist | Die entsprechende Aufgabe wurde bereits gesendet oder die Schedule-ID ist falsch. |
| 28105 | 404 | Kein Push-Ziel für die festgelegte Zeit | The push task is invalid. There is no push target for the scheduled time | Fehlerhafter Push-Zeitparameter. |
| 28200 | 500 | Interner Serverfehler | Server Internal error. | Unerwarteter Fehler aufgetreten. |
| 28203 | 503 | Interner Serverfehler, bitte später erneut versuchen | Execute action timeout, please try later again | Kommunikationsfehler mit dem Schedule-Server. |
Weitere Informationen zur API Dokumentation, Zeitplan-API und Push-Benachrichtigung finden Sie in unseren weiterführenden Ressourcen.
Jetzt Zeitpläne effizient verwalten – API testen!

