Push (FCM & APNs)

Syntra delivers push notifications through Engage using FCM HTTP v1 for Android and web, and APNs HTTP/2 for iOS. Configure providers per tenant, register device tokens, then send via Route or Engage test endpoints.

Prerequisites

• Enable the push feature for your tenant (Console → Settings → Feature access)
• FCM: Firebase project + service account JSON with firebase.messaging scope
• APNs: .p8 auth key (Key ID, Team ID, Bundle ID) converted to PEM
• Permission: engage:channels:read|write for config/devices; route:messages:write to send

Configure providers

{
  "fcmProjectId": "my-firebase-project",
  "fcmServiceAccount": { "type": "service_account", "project_id": "...", "private_key": "..." },
  "apnsKeyId": "ABCD1234",
  "apnsTeamId": "TEAM123456",
  "apnsBundleId": "com.example.app",
  "apnsKeyPem": "-----BEGIN PRIVATE KEY-----\n...",
  "apnsUseSandbox": true,
  "defaultSound": "default"
}

Register device tokens

{
  "token": "fcm_or_apns_device_token",
  "platform": "android",
  "userId": "usr_demo",
  "appVersion": "1.2.0",
  "locale": "en-GH"
}

Recipient addressing

• user:{userId}: all active devices registered to that user
• device:{deviceId}: a specific registered device record
• ios:{token}: direct APNs device token
• android:{token}: direct FCM registration token

Send via Route

{
  "channel": "push",
  "to": "user:usr_demo",
  "push": {
    "title": "Payment received",
    "body": "GHS 120.00 credited to your wallet.",
    "data": { "txnId": "txn_abc", "screen": "wallet" },
    "badge": 1,
    "sound": "default",
    "imageUrl": "https://cdn.example.com/banner.png"
  }
}

Test from console or API

{
  "to": "device:pdev_abc123",
  "title": "Syntra test",
  "body": "Push channel is configured correctly."
}

Delivery behavior

• Route accepts messages with status accepted; Engage route-delivery worker sends to FCM/APNs
• Invalid or expired tokens are auto-revoked when providers return unregistered errors
• Usage is metered as route/push (1 unit per delivered notification)
• iOS silent/background pushes: set push.contentAvailable: true