Skip to Content
LYNKORIADocs

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:

CallPurpose
PUT /v1/push/devicesRegister 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

TriggerAndroid (FCM)iOS
POST /v1/calls/{id}/signal with type: invitedHigh-priority data messageVoIP push (PushKit → CallKit); alert if no VoIP token
POST /v1/calls/{id}/signal with type: endedHigh-priority data messageBackground push to the regular token (never VoIP)
POST /v1/notifications (service key, messaging:write)Notification or data messageAlert 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 responseResult
Successsent
FCM UNREGISTERED/404, APNs 410 / BadDeviceToken / UnregisteredDevice token invalidated; delivery failed
429, 5xx, network errors, expired provider tokensRetried with exponential backoff (2 s → 5 min), up to 6 attempts, honouring Retry-After
Expired before deliverydead (expired)
Other 4xx, missing credentialsdead, 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).

On this page