nself-notify: Push Notifications

Send push notifications to iOS and Android devices from your nself backend. Supports Firebase Cloud Messaging (FCM) for Android and Apple Push Notification service (APNs) for iOS, plus Web Push for browsers.

Install

nself license set nself_pro_...
nself plugin install notify
nself build
nself start

Configuration

Environment Variables

Add these to your .env file after installing the plugin:

PLUGIN_NOTIFY_FCM_SERVER_KEY=AAAAxxxxxxxx...
PLUGIN_NOTIFY_APNS_KEY_ID=ABCD1234EF
PLUGIN_NOTIFY_APNS_TEAM_ID=TEAM123456
PLUGIN_NOTIFY_APNS_KEY_PATH=/etc/nself/keys/AuthKey_ABCD1234EF.p8

Quick Start

Send a Notification

# Send a push notification to a user
curl -X POST http://127.0.0.1:3712/notify/send \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "fcm",
    "user_id": "user-uuid",
    "title": "New message",
    "body": "You have a new message from Alice",
    "data": {
      "conversation_id": "conv-123",
      "type": "chat"
    }
  }'

Subscribe a Device

# Register a device token for a user
curl -X POST http://127.0.0.1:3712/notify/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-uuid",
    "platform": "android",
    "device_token": "fcm-device-token-here"
  }'

Channels

API Reference

Send Payload

{
  "channel": "fcm",          // fcm | apns | webpush
  "user_id": "uuid",         // send to all devices for this user
  "device_token": "token",   // OR send to a specific device token
  "title": "string",         // notification title
  "body": "string",          // notification body text
  "data": {},                // optional key-value payload for the app
  "badge": 1,                // iOS badge count (optional)
  "sound": "default"         // notification sound (optional)
}

Subscribe Payload

{
  "user_id": "uuid",
  "platform": "android",   // android | ios | web
  "device_token": "string" // FCM token, APNs token, or Web Push subscription
}

Database Tables

The plugin creates a np_notify schema. Tables are auto-tracked by Hasura and accessible via GraphQL.

# List active devices for a user
query UserDevices($userId: uuid!) {
  np_notify_devices(where: {
    user_id: { _eq: $userId }
    active: { _eq: true }
  }) {
    platform
    registered_at
    last_seen
  }
}

# Recent delivery failures
query RecentFailures {
  np_notify_send_log(
    where: { status: { _eq: "failed" } }
    order_by: { sent_at: desc }
    limit: 20
  ) {
    user_id
    channel
    title
    error_message
    sent_at
  }
}

Events Emitted

These events are published to the nself event bus and can be consumed by nself-mux rules.

vs SaaS Alternatives

Troubleshooting

FCM: InvalidRegistration error

The device token is stale — the app was reinstalled or the user cleared app data. Delete the row from np_notify.devices where device_token matches, then have the app re-register.

APNs: BadDeviceToken error

Same as FCM invalid registration — the token expired. Ensure your app calls the subscribe endpoint with a fresh token after every app launch and after the OS generates a new APNs token.

iOS notifications not delivered in production

Confirm PLUGIN_NOTIFY_APNS_KEY_PATH points to a .p8 file that corresponds to the PLUGIN_NOTIFY_APNS_KEY_ID. Development and production APNs environments use the same key file but the apns-environment header differs — the plugin uses production by default.

Web Push: no VAPID keys configured

VAPID keys are auto-generated on first run and stored in np_notify config. If you see “VAPID keys not configured”, run nself restart to let the plugin initialize, then check /notify/health.

Checking delivery status

# View recent send log
curl http://127.0.0.1:3712/notify/health

# Or query directly via GraphQL
# SELECT status, error_message FROM np_notify.send_log ORDER BY sent_at DESC LIMIT 20;

Uninstall

nself plugin remove notify

Related

• Plugin Overview: Tier table, license setup, lifecycle commands
• nself-cron: Schedule notifications with cron jobs
• nself-mux: Route messages across channels including push
• nself-google: Trigger notifications from Google Calendar events

Port: 3712 | Bundle: ɳClaw ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.1.0