Notifications

Pushy Notifications

Device token registration, topic subscriptions, and dev push sends.

Overview

Use these routes for two related tasks:

  1. Managing device tokens and topic subscriptions.
  2. Sending push notifications to device tokens from a dev-oriented API endpoint.

Relevant routes:

  • POST /api/v2/device-info
  • GET /api/v2/device-info
  • POST /api/v2/device-info/subscribe
  • POST /api/v2/device-info/unsubscribe
  • GET /api/v2/device-info/topics/{topic}/subscribers
  • POST /api/v2/notifications/send-dev

All of these routes should be treated as protected and called with:

Authorization: Bearer <access_token>

1. Register Device Token

POST /api/v2/device-info

Stores the current device token for the authenticated user.

This route accepts both plain JSON and the encrypted wrapper payload format described in the overview.

Request

{
  "token": "pushy-device-token",
  "platform": "ANDROID",
  "language": "en"
}

Notes

  • platform must be one of IOS, ANDROID, or WEB.
  • language currently accepts en or zh.
  • Registering a token refreshes the active device binding for that user and prevents the same token from remaining active under another user.

Success response

{
  "status_code": 201,
  "message": "Success",
  "data": {
    "token": "pushy-device-token",
    "platform": "ANDROID"
  }
}

2. List Registered Device Tokens

GET /api/v2/device-info

Returns device token rows linked to the authenticated mobile user.

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": [
    {
      "token": "pushy-device-token",
      "platform": "ANDROID"
    }
  ]
}

3. Subscribe a Device Token to Topics

POST /api/v2/device-info/subscribe

Subscribes a token to one or more Pushy topics.

Request

{
  "token": "pushy-device-token",
  "topics": ["announcements", "system-updates"]
}

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "success": true,
    "message": "Successfully subscribed to topics"
  }
}

4. Unsubscribe a Device Token

POST /api/v2/device-info/unsubscribe

Unsubscribes a token from specific topics.

Request

{
  "token": "pushy-device-token",
  "topics": ["announcements"]
}

Notes

  • If topics is omitted or empty, the handler falls back to ["*"].
  • Invalid device-token errors are surfaced as a bad request.

5. Inspect Topic Subscribers

GET /api/v2/device-info/topics/{topic}/subscribers

Returns the Pushy device tokens currently subscribed to the requested topic.

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "topic": "announcements",
    "subscribers": ["pushy-device-token"]
  }
}

6. Send a Dev Push Notification

POST /api/v2/notifications/send-dev

Sends a push notification to one or more device tokens through Pushy.

This route also accepts plain JSON and the encrypted wrapper format.

Request

{
  "title": "Balance Updated",
  "content": "Your wallet has been credited.",
  "to": ["pushy-device-token"],
  "action": "wallet_refresh",
  "additional_data": {
    "wallet_id": 17,
    "source": "topup"
  }
}

Payload behavior

  • title and content are required.
  • to must contain at least one device token.
  • action, when present, is merged into the notification data payload.
  • additional_data is merged into the same Pushy data payload as top-level keys.

Success response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "success": true,
    "message": "Notification sent successfully"
  }
}

Response note

The API returns only a success flag and message. Detailed delivery diagnostics are not included in this endpoint response.

Current Limits

The current Pushy integration enforces:

  • Maximum payload size: 4096 bytes
  • Maximum devices per request: 100000

Common underlying Pushy error mappings:

  • NO_RECIPIENTS
  • NO_APNS_AUTH
  • PAYLOAD_LIMIT_EXCEEDED
  • INVALID_DEVICE_TOKEN

If you hit these conditions, the API responds with the project’s normal JSON error envelope.

Copyright © 2026