EngageLab App Push API Skill

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:

1. Create Push — Send notification or message to single/multiple devices (broadcast, tag, alias, registration_id, segment)
2. Batch Single Push — Batch push by registration_id or alias (up to 500 per request)
3. Group Push — Push to all apps in a group
4. Push Plan — Create/update/list push plans and query msg_ids by plan
5. Scheduled Tasks — Create, get, update, delete scheduled push tasks (single, periodical, intelligent)
6. Tag & Alias — Query/set/delete device tags and aliases; query tag count
7. Message Recall — Recall a pushed message (within one day)
8. Delete User — Delete a user (registration_id) and all associated data
9. Statistics — Message lifecycle stats, report APIs
10. Callback — Webhook setup and signature verification
11. Test Push — Validate push request without sending
12. Image API — OPPO big/small picture upload
13. Push-to-Speech — Create/update voice broadcast files

Resources

scripts/

• 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.

references/

• error-codes.md — Push API error codes and descriptions
• http-status-code.md — HTTP status code specification
• callback-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).

Authentication

All EngageLab App Push API calls use HTTP Basic Authentication.

• Base URL (choose by data center):
  • Singapore: https://pushapi-sgp.engagelab.com
  • Virginia, USA: https://pushapi-usva.engagelab.com
  • Frankfurt: https://pushapi-defra.engagelab.com
  • Hong Kong: https://pushapi-hk.engagelab.com
• Header: Authorization: Basic base64(appKey:masterSecret)
• Content-Type: 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.

Request Rate Limits

• Standard: 500 requests per second per AppKey.
• Batch Single Push shares the same QPS quota as the Push API (1 target = 1 QPS).

Quick Reference — Main Endpoints

Create Push (POST /v4/push)

Push a notification or message to a single device or list of devices. Body is JSON.

Request structure (summary)

body

*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.

Push target to examples

• Broadcast: "to": "all"
• Tags (OR): "to": { "tag": ["Shenzhen","Guangzhou"] }
• Tags (AND): "to": { "tag_and": ["female","members"] }
• Alias: "to": { "alias": ["user1","user2"] }
• Registration IDs: "to": { "registration_id": ["id1","id2"] }
• Segment: "to": { "seg": { "id": "segid" } }
• Live Activity: "to": { "live_activity_id": "LiveActivity-1" }

Response (success)

{ "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.

Batch Single Push

• By registration_id: POST /v4/batch/push/regid
• By alias: POST /v4/batch/push/alias

Request 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.

Group Push

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.

Push Plan

• Create/update: POST /v4/push_plan — Body: { "plan_id": "xxx", "plan_description": "..." }.
• List: GET /v4/push_plan/list?page_index=1&page_size=20&send_source=0|1&search_description=xxx.
• Msg IDs by plan: 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.

Scheduled Tasks

• Create: POST /v4/schedules — Body includes name, enabled, trigger (single / periodical / intelligent), push (same as Create Push body).
• Get: GET /v4/schedules/{schedule_id}.
• Update: PUT /v4/schedules/{schedule_id}.
• Delete: 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.

Tag & Alias

• Tag count: GET /v4/tags_count?tags=tag1&tags=tag2&platform=android|ios|hmos (up to 1000 tags).
• Get device: GET /v4/devices/{registration_id} — Returns tags, alias.
• Set device: 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.

Message Recall

DELETE /v4/push/withdraw/{msg_id} — Recall within one day; no duplicate recall.

Delete User

DELETE /v4/devices/{registration_id} — Asynchronously deletes user and all related data (tags, alias, device info, timezone). Cannot be restored. Batch deletion not supported.

Statistics

• Message detail: 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.

Callback

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.

Test Push

POST /v4/push/validate — Same body as Create Push. Validates request without sending to users.

Image API (OPPO)

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.

Push-to-Speech

• Create/update: POST /v4/voices — Content-Type: multipart/form-data; fields: language (en, zh-Hans, zh-Hant), file (zip of mp3 files). Returns file_url.
• List: GET /v4/voices.
• Delete: 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.

Generating Code

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:

• curl — Shell with -u "AppKey:MasterSecret" and correct base URL
• Python — requests with Basic auth
• Node.js — fetch or axios
• Java — HttpClient
• Go — net/http

Always include the Authorization header and error handling. Use placeholders like YOUR_APP_KEY and YOUR_MASTER_SECRET if credentials are not provided.

Python Example — Create Push

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"))