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...
---
name: engagelab-apppush
description: >
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 scheduled
tasks and push plans; batch push; recall messages; query statistics; and
configure callbacks. Use this skill when the user wants to send push notifications
via EngageLab, manage device tags/aliases, schedule pushes, use batch single push,
group push, message recall, delete users, query push statistics, validate push
requests, upload images for OPPO, use push-to-speech, or integrate with EngageLab
App Push. Also trigger for "engagelab push", "app push api", "push notification",
"registration_id", "tag alias", "scheduled push", "push plan", "batch push",
"message recall", "push statistics", "push callback", or "MTPush".
---
# 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):
```bash
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
| 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` |
## Create Push (`POST /v4/push`)
Push a notification or message to a single device or list of devices. Body is JSON.
### Request structure (summary)
| 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 |
### body
| 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.
### 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)
```json
{ "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
```python
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"))
```
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit inputs section with credential and rate limit details, expanded procedure into six sequential steps with clear inputs/outputs per step, created decision points for auth, broadcast, batch limits, rate limits, recalls, stats retention, user deletion, file uploads, and callback setup, formalized output contract with response formats for each operation type, and defined outcome signals for success across all operations including error handling.
send push notifications and in-app messages to android, ios, and harmonyos devices via engagelab's app push api (mtpush). use this skill when the user needs to broadcast or target push notifications, manage device tags and aliases, schedule pushes, batch send messages, recall sent messages, query delivery stats, or integrate callback webhooks. covers single push, batch push, group push, push plans, scheduled tasks, device management, message recall, user deletion, statistics, callbacks, test validation, image uploads, and text-to-speech.
engagelab app push credentials (required):
APP_KEY: application key from console, application settings, application infoMASTER_SECRET: master secret from console, application settings, application infoENGAGELAB_APP_KEY and ENGAGELAB_MASTER_SECRET, or provide at runtimebase url (required):
https://pushapi-sgp.engagelab.com, virginia usa https://pushapi-usva.engagelab.com, frankfurt https://pushapi-defra.engagelab.com, hong kong https://pushapi-hk.engagelab.comENGAGELAB_BASE_URL or pass as parametergroup push credentials (conditional, if using group push):
GROUP_KEY: group identifierGROUP_MASTER_SECRET: group master secretgroup-{GROUP_KEY} as username instead of app keyhttp basic authentication:
Authorization: Basic base64(appKey:masterSecret)application/json (or multipart/form-data for image/voice uploads)external rate limits:
optional inputs (context-dependent):
push_plan_id: to associate push with a push planschedule_id: for updating/deleting scheduled tasksregistration_id: device identifier for single device operationsmsg_id: message identifier for recall or stats queriestags: device tags for targeting (up to 100 per device, 100,000 total per app)alias: device alias (one per device, 40 bytes max)timezone: for scheduled push time_zone contextinput: user request (intent: send push, manage tags, etc.)
ENGAGELAB_APP_KEY and ENGAGELAB_MASTER_SECRET env vars existGROUP_KEY and GROUP_MASTER_SECRET
output: app_key, master_secret, base_url confirmed; group credentials (if applicable)input: user request details (push content, targets, scheduling info, etc.)
input: app_key, master_secret (or group_key, group_master_secret for group push)
base64(app_key + ":" + master_secret) (or group credentials)Authorization: Basic {encoded_credentials}
output: authorization header string ready for http requestinput: endpoint path, http method (post/get/put/delete), request body, authorization header, base_url
/v4/push, /v4/batch/push/regid, /v4/batch/push/alias, /v4/grouppush, /v4/push_plan, /v4/schedules, /v4/devices/{registration_id}, /v4/push/validate, /v4/image/oppo, /v4/voices/v4/push_plan/list, /v4/status/plan/msg/, /v4/schedules/{schedule_id}, /v4/tags_count, /v4/devices/{registration_id}, /v4/status/detail, /v4/voices/v4/schedules/{schedule_id}/v4/schedules/{schedule_id}, /v4/devices/{registration_id}, /v4/push/withdraw/{msg_id}, /v4/voicesContent-Type: application/json (multipart/form-data for image/voice)Authorization: Basic {encoded_credentials}input: http response, operation type
input: parsed response from step 5, operation type
if user has not provided app key and master secret, do this:
if user specifies group push, do this:
group-{group_key} in authorization headerif user has multiple data center options and did not specify, do this:
https://pushapi-sgp.engagelab.comif push targets are not specified (broadcast), do this:
"to": "all" in request bodyif user provides both notification and message in same push, do this:
if user requests batch push with more than 500 targets, do this:
if rate limit is hit (status 429), do this:
if response is empty or malformed, do this:
if user wants to recall a message (within one day), do this:
DELETE /v4/push/withdraw/{msg_id}if user requests message statistics, do this:
if user is deleting a device/user (registration_id), do this:
if user uploads images or voice files, do this:
if user is setting up callbacks, do this:
successful push (create/batch/group):
{ "request_id": "req_xxx", "msg_id": "msg_yyy" } or for batch: { "request_id": "req_xxx", "data": [ { "target": "id", "msg_id": "msg_yyy" } ] }successful schedule create:
{ "schedule_id": "schedule_xxx", ... }successful tag/alias operations:
{ "tags": ["tag1"], "alias": "alias1" } (http 200){ "status": "ok" } (http 200){ "results": [ { "tag": "tag1", "count": 100 } ] } (http 200)successful stats query:
{ "message_ids": [ { "msg_id": "xxx", "sent": N, "delivered": N, "impressions": N, "clicks": N, ... } ] }successful validation (test push):
{ "status": "ok" } or error details (http 200)error responses:
error or error_code field with descriptionfile outputs (image/voice uploads):
{ "big_picture_id": "id1", "small_picture_id": "id2" } (image) or { "file_url": "url" } (voice)user knows push was sent successfully when:
user knows batch push succeeded when:
data array with per-target resultsuser knows scheduled task was created when:
user knows message was recalled when:
user knows device tags/alias were updated when:
status: "ok" or device infouser knows stats query succeeded when:
user knows image/voice upload succeeded when:
user knows callback is validated when:
user knows request failed when: