Call EngageLab App Push REST APIs to send push notifications and in-app messages to Android, iOS, and HarmonyOS devices; manage tags and aliases; create sche...
This skill enables interaction with the EngageLab App Push REST API (MTPush). The service supports push notifications and in-app messages to Android, iOS, and HarmonyOS, with multi-vendor channel support (FCM, Huawei, Xiaomi, OPPO, vivo, Meizu, Honor, etc.).
It covers these areas:
push_client.py — Python client class (EngageLabPush) wrapping create push, batch push (regid/alias), device get/set/delete, tag count, message recall, validate push, push plan create/list, scheduled tasks CRUD, and message detail stats. Handles Basic auth and typed error handling. Use as a helper or import into the user's project.error-codes.md — Push API error codes and descriptionshttp-status-code.md — HTTP status code specificationcallback-api.md — Callback address, validation, security (X-CALLBACK-ID, HMAC-SHA256)Source API docs: doc/apppush/REST API/ (Create Push API, Batch Single Push API, Group Push API, Push Plan API, Scheduled Tasks API, Tag Alias API, Message Recall, Delete User API, Statistics API, Callback API, Test Push API, imageAPI, Push-to-Speech API, REST API OVERVIEW, HTTP Status code).
All EngageLab App Push API calls use HTTP Basic Authentication.
https://pushapi-sgp.engagelab.comhttps://pushapi-usva.engagelab.comhttps://pushapi-defra.engagelab.comhttps://pushapi-hk.engagelab.comAuthorization: Basic base64(appKey:masterSecret)application/json (or multipart/form-data for Image/Push-to-Speech as specified)Obtain AppKey and Master Secret from Console → Application Settings → Application Info.
Group Push uses a different auth: username = group- + GroupKey, password = Group Master Secret (from Group management).
Example (curl):
curl -X POST https://pushapi-sgp.engagelab.com/v4/push \
-H "Content-Type: application/json" \
-u "YOUR_APP_KEY:YOUR_MASTER_SECRET" \
-d '{ "from": "push", "to": "all", "body": { "platform": "all", "notification": { "alert": "Hello!" } } }'
If the user hasn't provided credentials, ask for AppKey and Master Secret before generating API calls.
| Operation | Method | Path |
|---|---|---|
| Create push | POST | /v4/push |
| Batch push by registration_id | POST | /v4/batch/push/regid |
| Batch push by alias | POST | /v4/batch/push/alias |
| Group push | POST | /v4/grouppush |
| Create/update push plan | POST | /v4/push_plan |
| List push plans | GET | /v4/push_plan/list |
| Msg IDs by plan | GET | /v4/status/plan/msg/ |
| Create scheduled task | POST | /v4/schedules |
| Get scheduled task | GET | /v4/schedules/{schedule_id} |
| Update scheduled task | PUT | /v4/schedules/{schedule_id} |
| Delete scheduled task | DELETE | /v4/schedules/{schedule_id} |
| Tag count | GET | /v4/tags_count |
| Get device (tags/alias) | GET | /v4/devices/{registration_id} |
| Set device tags/alias | POST | /v4/devices/{registration_id} |
| Delete device (user) | DELETE | /v4/devices/{registration_id} |
| Message recall | DELETE | /v4/push/withdraw/{msg_id} |
| Message statistics | GET | /v4/status/detail (message_ids) |
| Test push (validate) | POST | /v4/push/validate |
| OPPO image upload | POST | /v4/image/oppo |
| Create/update voice | POST | /v4/voices |
| List/delete voices | GET / DELETE | /v4/voices |
POST /v4/push)Push a notification or message to a single device or list of devices. Body is JSON.
| Field | Type | Required | Description |
|---|---|---|---|
from | string | No | Sender, e.g. "push" |
to | string or object | Yes | Target: "all" (broadcast), or object with tag, tag_and, tag_not, alias, registration_id, live_activity_id, seg |
body | object | Yes | See below |
request_id | string | No | Client-defined request ID returned in response |
custom_args | object | No | Returned on callback, max 128 chars |
| Field | Type | Required | Description |
|---|---|---|---|
platform | string or array | Yes | "all" or ["android","ios","hmos"] |
notification | object | Optional* | Notification content (android, ios, hmos; alert, title, extras, etc.) |
message | object | Optional* | In-app/custom message (msg_content, title, content_type, extras) |
live_activity | object | Optional* | iOS Live Activity (ios.event, content-state, attributes, etc.) |
voip | object | Optional* | iOS VoIP (key-value); cannot coexist with notification/message/live_activity |
options | object | No | time_to_live, apns_production, apns_collapse_id, big_push_duration, multi_language, third_party_channel, plan_id, cid, etc. |
*One of notification, message, live_activity, or voip must exist; they cannot coexist (except notification+message in some cases — see doc). For iOS, set options.apns_production (true/false) for environment.
to examples"to": "all""to": { "tag": ["Shenzhen","Guangzhou"] }"to": { "tag_and": ["female","members"] }"to": { "alias": ["user1","user2"] }"to": { "registration_id": ["id1","id2"] }"to": { "seg": { "id": "segid" } }"to": { "live_activity_id": "LiveActivity-1" }{ "request_id": "12345678", "msg_id": "1828256757" }
For full parameter details (android/ios/hmos notification fields, options, multi_language, third_party_channel, push limits per vendor), see doc/apppush/REST API/Create Push API.md. Error codes: references/error-codes.md.
POST /v4/batch/push/regidPOST /v4/batch/push/aliasRequest body: { "requests": [ { "target": "reg_id_or_alias", "platform": "android"|"ios"|"all", "notification": {...}, "message": {...}, "options": {...}, "custom_args": {...} } ] }. Max 500 items per request; target must be unique in the batch. Response returns per-target result (msg_id or error). See doc/apppush/REST API/Batch Single Push API.md.
POST /v4/grouppush — Same body structure as Create Push. Auth: Basic with group-{GroupKey} and Group Master Secret. Response includes group_msgid and per-app msg_id. override_msg_id and Schedule API are not supported for group push.
POST /v4/push_plan — Body: { "plan_id": "xxx", "plan_description": "..." }.GET /v4/push_plan/list?page_index=1&page_size=20&send_source=0|1&search_description=xxx.GET /v4/status/plan/msg/?plan_ids=id1,id2&start_date=yyyy-MM-dd&end_date=yyyy-MM-dd (within 30 days, max 31 days span).Use plan_id in Create Push body.options to associate a push with a plan.
POST /v4/schedules — Body includes name, enabled, trigger (single / periodical / intelligent), push (same as Create Push body).GET /v4/schedules/{schedule_id}.PUT /v4/schedules/{schedule_id}.DELETE /v4/schedules/{schedule_id}.Trigger types: single (one-time, time, zone_type), periodical (start, end, time, time_unit, point, zone_type), intelligent (backup_time: "now" or "yyyy-MM-dd HH:mm:ss"). See doc/apppush/REST API/Scheduled Tasks API.md.
GET /v4/tags_count?tags=tag1&tags=tag2&platform=android|ios|hmos (up to 1000 tags).GET /v4/devices/{registration_id} — Returns tags, alias.POST /v4/devices/{registration_id} — Body: { "tags": { "add": ["t1"], "remove": ["t2"] }, "alias": "alias1" }.Limits: 100,000 tags per app; 40 bytes per tag; 100 tags per device; 100,000 devices per tag; one alias per device (40 bytes). See doc/apppush/REST API/Tag Alias API.md.
DELETE /v4/push/withdraw/{msg_id} — Recall within one day; no duplicate recall.
DELETE /v4/devices/{registration_id} — Asynchronously deletes user and all related data (tags, alias, device info, timezone). Cannot be restored. Batch deletion not supported.
GET /v4/status/detail?message_ids=id1,id2 (up to 100 message_ids). Returns targets, sent, delivered, impressions, clicks, and sub-stats by channel. Data retained up to one month.Other report endpoints (e.g. report APIs) are documented in doc/apppush/REST API/Statistics API.md.
Configure callback URL (via Engagelab support). Validation: server sends POST with echostr in body; respond with body = echostr value. Security: use X-CALLBACK-ID header; signature = HMAC-SHA256(secret, timestamp+nonce+username). Respond with 200/204 within 3 seconds for success. See references/callback-api.md and doc/apppush/REST API/Callback API.md.
POST /v4/push/validate — Same body as Create Push. Validates request without sending to users.
POST /v4/image/oppo — Body: { "big_picture_url": "url", "small_picture_url": "url" }. Returns big_picture_id, small_picture_id for use in push options (e.g. third_party_channel.oppo). OPPO constraints: big 984×369, ≤1MB; small 144×144, ≤50KB; PNG/JPG/JPEG.
POST /v4/voices — Content-Type: multipart/form-data; fields: language (en, zh-Hans, zh-Hant), file (zip of mp3 files). Returns file_url.GET /v4/voices.DELETE /v4/voices?language=en.Use options.voice_value in push body to reference voice for TTS. See doc/apppush/REST API/Push-to-Speech API.md.
When the user asks to send push or use other App Push APIs, generate working code. Default to curl unless the user specifies a language. Supported patterns:
-u "AppKey:MasterSecret" and correct base URLrequests with Basic authfetch or axiosHttpClientnet/httpAlways include the Authorization header and error handling. Use placeholders like YOUR_APP_KEY and YOUR_MASTER_SECRET if credentials are not provided.
import requests
APP_KEY = "YOUR_APP_KEY"
MASTER_SECRET = "YOUR_MASTER_SECRET"
BASE_URL = "https://pushapi-sgp.engagelab.com"
resp = requests.post(
f"{BASE_URL}/v4/push",
auth=(APP_KEY, MASTER_SECRET),
headers={"Content-Type": "application/json"},
json={
"from": "push",
"to": "all",
"body": {
"platform": "all",
"notification": {
"alert": "Hello, Push!",
"android": {"alert": "Hi, Android!", "title": "Title"},
"ios": {"alert": "Hi, iOS!", "sound": "default", "badge": "+1"},
},
"options": {"time_to_live": 86400, "apns_production": False},
},
"request_id": "req_001",
},
)
result = resp.json()
if resp.status_code == 200:
print("msg_id:", result.get("msg_id"))
else:
print("Error:", result.get("error"))
ZIP package — ready to use