​

Push notification categories

​

1. Why curate categories

• Interactive actions ship uniformly. Instead of passing per-platform overrides on every send, you name one identifier and the send path expands its stored iOS actions, Android tap action, and sound.
• APNs payload rules are enforced at curation time. Identifiers are validated as UPPER_SNAKE_CASE (max 64 chars), action titles are capped at 128 chars, and a category carries at most 10 actions — the constraints APNs enforces are caught when you author the category, not when APNs rejects a mis-shaped payload with a per-device failed result.
• Identifiers are wire-bound. The iOS / Android client registers and matches on the identifier string, so categories are immutable after create — delete and recreate to change one. This keeps in-flight pushes referencing the shape the client cached.

​

2. Manage categories in the dashboard

​

3. Category shape

curl -X POST https://api.orbit.devotel.io/api/v1/push/categories \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice reminders",
    "identifier": "INVOICE_REMINDER",
    "sound": "chime.aiff",
    "actions": [
      { "identifier": "PAY_NOW", "title": "Pay now", "options": ["foreground"] },
      { "identifier": "SNOOZE", "title": "Snooze", "options": ["background"] }
    ]
  }'

​

4. Apply a category on send

curl -X POST https://api.orbit.devotel.io/api/v1/push/send \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user_8a1f2c"],
    "title": "Invoice #1042 is due",
    "body": "Tap to review and pay.",
    "notification_channel": "INVOICE_REMINDER"
  }'

• iOS — the APNs payload carries category: "INVOICE_REMINDER", plus the category’s custom sound unless the send’s own ios.sound override wins. If the send supplies no actions of its own, the category’s stored actions fill in.
• Android — the FCM click_action is set to the identifier, and unless you override android.channel_id explicitly, notification_channel doubles as the Android channel id.
• Unresolved identifier — the send proceeds as a plain notification; naming an unknown identifier is not a failure.

​

5. End-to-end example

1. Create the category — with the PAY_NOW / SNOOZE actions shown above, or through the dashboard’s Notification Categories page.
2. Send a test push — fire POST /api/v1/push/test-send with "notification_channel": "INVOICE_REMINDER" against your own devices to validate the whole chain without polluting campaign stats.
3. Verify on device — the iOS device renders the notification with the registered PAY NOW / SNOOZE buttons and the custom chime; Android routes the tap through click_action: "INVOICE_REMINDER".
4. Read the result — each device in notifications[] reports sent; a failed row on an unregistered device still carries a raw provider error such as BadDeviceToken for you to act on.