Push notifications and incoming calls
Device registration, automatic incoming-call pushes, product notifications, delivery and failure handling.
Lynkoria delivers pushes through Firebase Cloud Messaging (Android) and Apple Push Notification service (iOS), including PushKit VoIP pushes for CallKit. Delivery has been tested only against local mocks of the FCM and APNs endpoints, not through Google or Apple.
Credentials
Push credentials are product-managed: each product creates its own Firebase service account and APNs token-signing key (.p8), and the platform operator stores them in the API's PUSH_CREDENTIALS_JSON. An environment references them with pushCredentialRef. Secrets never pass through the API, the console or any client.
{
"vibelynk-prod": {
"fcm": {
"projectId": "vibelynk",
"clientEmail": "push@vibelynk.iam.gserviceaccount.com",
"privateKey": "<PEM-encoded private key from the service account JSON>"
},
"apns": {
"teamId": "ABCDE12345",
"keyId": "KEY1234567",
"privateKey": "<PEM-encoded private key from the APNs .p8 file>",
"bundleId": "com.guildsman.vibelynk"
}
}
}Then, in the console or admin API, set the environment's pushCredentialRef to vibelynk-prod and enable the push feature.
Registering devices
Devices register themselves with their messaging token, so the user and device always come from the verified token:
| Call | Purpose |
|---|---|
PUT /v1/push/devices | Register or refresh a token (call on every refresh). provider: fcm, apns or apns_voip |
DELETE /v1/push/devices?provider=… | Unregister on sign-out |
GET/PUT /v1/push/preferences | { calls, messages } opt-outs per user |
A token re-registered by a different user (a shared phone) moves to the new user. Multiple devices per user are supported.
What gets sent
| Trigger | Android (FCM) | iOS |
|---|---|---|
POST /v1/calls/{id}/signal with type: invited | High-priority data message | VoIP push (PushKit → CallKit); alert if no VoIP token |
POST /v1/calls/{id}/signal with type: ended | High-priority data message | Background push to the regular token (never VoIP) |
POST /v1/notifications (service key, messaging:write) | Notification or data message | Alert or background push |
Call pushes expire after 45 seconds, so late deliveries never ring. Include callerName or title in the signal data to show a name. Payload keys: lynkoria_kind, lynkoria_call_id, lynkoria_call_type, lynkoria_from_user_id, lynkoria_caller_name, lynkoria_tenant_id, lynkoria_sent_at. Keep custom data small and free of secrets or message content you would not show on a lock screen.
Missed calls. When a call_cancelled push arrives for a call that is still ringing, the Android SDK replaces the ringing notification with a missed-call notification and the iOS SDK ends the CallKit call. Your backend decides when a call is cancelled or missed and sends ended.
Delivery
A worker claims pending deliveries every second (FOR UPDATE SKIP LOCKED, safe across replicas). Outcomes:
| Provider response | Result |
|---|---|
| Success | sent |
FCM UNREGISTERED/404, APNs 410 / BadDeviceToken / Unregistered | Device token invalidated; delivery failed |
| 429, 5xx, network errors, expired provider tokens | Retried with exponential backoff (2 s → 5 min), up to 6 attempts, honouring Retry-After |
| Expired before delivery | dead (expired) |
| Other 4xx, missing credentials | dead, logged |
Metrics: lynkoria_push_deliveries_total{provider,result}. The console's Operations tab lists recent deliveries.
Testing on devices
Real delivery needs real credentials and devices; see testing completion criteria. Use apnsEnvironment: "sandbox" with development builds; production tokens fail against the sandbox host and vice versa (reported as invalid).