Sending Push Notifications

Once devices are registered, you can send push notifications to users. Mushu supports single-user notifications and bulk sends.

What This Is

Mushu sends push notifications through Apple Push Notification service (APNs). You provide a user ID and notification content, and Mushu delivers it to all devices registered for that user.

When to Use

• Alerting users about new messages, events, or updates
• Sending silent pushes to trigger background data sync
• Updating badge counts

Sending a Notification

CLI

mushu push send \
  --user USER_ID \
  --title "Hello" \
  --body "You have a new message"

API

POST /tenants/{tenant_id}/notify
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "user_id": "user-123",
  "alert": {
    "title": "Hello",
    "body": "You have a new message"
  }
}

Notification Options

Field	Type	Description
user_id	string	Required. The user to send to.
alert.title	string	Notification title (bold text)
alert.body	string	Notification body text
badge	number	App icon badge count
sound	string	Sound name (or "default")
data	object	Custom data payload
content_available	boolean	Silent/background push

Examples

With Badge and Sound

mushu push send \
  --user USER_ID \
  --title "New Message" \
  --body "John sent you a message" \
  --badge 5 \
  --sound default

With Custom Data

mushu push send \
  --user USER_ID \
  --title "Order Update" \
  --body "Your order has shipped" \
  --payload '{"order_id": "12345", "action": "view_order"}'

Silent Push

Silent pushes wake your app in the background without showing a notification:

mushu push send \
  --user USER_ID \
  --silent \
  --payload '{"sync": true}'

Bulk Sending

Send the same notification to multiple users at once:

CLI

mushu push bulk \
  --users "user-1,user-2,user-3" \
  --title "Announcement" \
  --body "Check out our new feature!"

API

POST /tenants/{tenant_id}/notify/bulk
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "user_ids": ["user-1", "user-2", "user-3"],
  "alert": {
    "title": "Announcement",
    "body": "Check out our new feature!"
  }
}

Response:

{
  "total": 3,
  "success": 2,
  "failed": 1
}

Handling the Notification (iOS)

extension AppDelegate: UNUserNotificationCenterDelegate {
    // Called when notification received while app is in foreground
    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                willPresent notification: UNNotification,
                                withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        // Show the notification even when app is open
        completionHandler([.banner, .sound, .badge])
    }

    // Called when user taps the notification
    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                didReceive response: UNNotificationResponse,
                                withCompletionHandler completionHandler: @escaping () -> Void) {
        let userInfo = response.notification.request.content.userInfo

        // Handle custom data
        if let orderId = userInfo["order_id"] as? String {
            navigateToOrder(orderId)
        }

        completionHandler()
    }
}

FAQ

What if the user has no registered devices?

The API returns success but with zero deliveries. This is not an error—the user simply has no devices to receive the notification.

How do I know if the push was delivered?

Mushu reports whether APNs accepted the notification. Actual delivery depends on device connectivity, notification settings, etc., which APNs doesn't report back.

What's the maximum payload size?

APNs limits payloads to 4KB. Mushu will reject notifications that exceed this limit.

Can I send to specific devices instead of users?

Currently, Mushu sends to all devices for a user. If you need device-specific targeting, use different user IDs for different devices.

How fast are notifications delivered?

Typically within seconds. APNs is very fast. If there's a delay, check your device's network connection and notification settings.