Push Notifications

Push notifications provide free, instant delivery to users who have your mobile or web app installed. They support rich content, deep links, and interactive actions.

When to use push

In-app engagement: activity updates, social notifications, content recommendations
Cost-sensitive messaging at scale: push is free regardless of volume
Rich notifications: images, action buttons, and deep links into specific app screens
Re-engagement: bring users back to your app with timely, relevant alerts

Sending a push notification

curl -X POST https://api.smooven.io/v1/agent/notify \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "push",
    "to": "player_id_abc123",
    "push": {
      "title": "New message from Sarah",
      "body": "Hey, are we still on for lunch tomorrow?",
      "icon": "https://example.com/sarah-avatar.png",
      "deep_link": "/conversations/sarah",
      "actions": [
        { "id": "reply", "title": "Reply" },
        { "id": "dismiss", "title": "Dismiss" }
      ]
    }
  }'

Supported platforms

Platform	Service	Token format
Android	Firebase Cloud Messaging (FCM)	FCM registration token
iOS	Apple Push Notification service (APNs)	Device token (hex string)
Web	Web Push (VAPID)	Push subscription JSON

Registering devices

Before sending push notifications, register the user’s device token with Smooven:

// Client-side: register a push token
await fetch('https://api.smooven.io/v1/players/register', {
  method: 'POST',
  headers: {
    'X-App-ID': 'app_live_xyz789...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_id: 'user_123',
    channels: {
      push: {
        platform: 'android',
        device_token: 'fcm_registration_token_here',
      },
    },
  }),
});

Push payload options

Parameter	Type	Description
`title`	string	Notification title
`body`	string	Notification body text
`icon`	string	URL to notification icon
`image`	string	URL to large image (Android, Web)
`deep_link`	string	App deep link or URL to open on tap
`badge`	number	App badge count (iOS)
`sound`	string	Notification sound (`default` or custom)
`ttl`	number	Time-to-live in seconds (how long to retry)
`actions`	array	Action buttons with `id` and `title`
`data`	object	Custom key-value pairs passed to your app

Delivery behaviour

Push notifications are best-effort delivery. Unlike SMS, there is no carrier-level guarantee. If the device is offline, notifications are queued by FCM/APNs and delivered when the device reconnects (subject to TTL).

Android: notifications delivered even if the app is not running
iOS: delivery depends on user permission and notification settings
Web: requires the browser to be running (not necessarily in the foreground)

Best practices

Respect user preferences. Only send relevant, timely notifications.
Use action buttons to give users quick response options.
Set appropriate TTL values. A flash sale notification is not useful 24 hours later.
Track engagement. Monitor open rates and adjust frequency accordingly.
Use Smart Routing to fall back to SMS or email for critical messages if push fails.