Push notifications

When your app is in the background or closed, it has no socket. poolse reaches it with push notifications, through Apple Push Notification service (APNs) on iOS and Firebase Cloud Messaging (FCM) on Android. poolse sends these itself. You do not need a push server.

What poolse sends

Push payloads lists every field.

What you provide

1. Your app's push credentials

Upload these on the dashboard's Push page. Pushes are signed with your credentials and addressed to your bundle id, so without them your app receives nothing.

• iOS: an APNs auth key (.p8), its Key ID, your Team ID, your app's bundle id, and the environment (production or sandbox). One key signs VoIP pushes and ordinary alerts.
• Android: a Firebase service-account JSON file, from the Firebase project your app's google-services.json belongs to. Note that the service account is a different file from google-services.json.

Configure one platform or both. Devices on a platform without credentials are skipped.

2. Device tokens

Each signed-in device registers its push token with POST /v1/devices (or poolse.devices.register()), using the user's JWT. See Devices.

An iPhone needs both tokens. Apple only allows a VoIP push to report an incoming call. Anything else must use the regular token.

environment (production or sandbox) says which APNs gateway the token belongs to. Debug builds use sandbox. If it is wrong, poolse retries on the other gateway, and on success records the right one for next time.

Registering is idempotent: register on every launch and whenever the OS rotates the token. The latest registration of a token wins: its user, platform, environment and kind all follow it, so a token registered again by a different user moves to that user. When a user signs out, call DELETE /v1/devices/:token, or the phone keeps getting their notifications. When Apple or Google reports a token as gone, poolse deletes it.

3. App code that handles the pushes

Android pushes are FCM data messages. They show nothing on their own; the app's code builds the notification or the incoming-call screen. iOS rings must be reported to CallKit right away.

@poolse/native does all of this in native code, even when the app is closed:

• ringing on CallKit and Android's full-screen call screen;
• chat notifications grouped by conversation, with Reply and Mark as read;
• missed calls with Call back.

See Push setup and Ringing phones end to end. Without @poolse/native you need your own native handling for every payload.

Notification settings

Set per workspace on the dashboard's Push → Notification settings.

Rules for chat notifications:

• They go to every member except the sender.
• Direct conversations always notify, whatever groups says.
• A mention always notifies the person mentioned.
• Only text messages notify. custom messages (your app's cards) and system messages (call logs) never do.

Delivery

• poolse knows only whether Apple or Google accepted a push. It cannot see whether the phone showed it.
• A push that cannot be delivered right away is kept by Apple or Google for a limited time. Rings: 60 seconds on Android; on iOS a VoIP push is not stored at all. Chat notifications and missed calls: 24 hours.
• The ring push is sent even to a device whose app is open. The app de-duplicates it against the socket by call_id.
• Delivery counts per day, platform and kind (accepted, failed, tokens removed) are on the dashboard's Push page, along with a test send.

Not available

• Sending your own custom push through poolse.
• Muting a conversation through the API: muted_until is honoured but cannot be set yet (see Conversations & roles).
• Per-user notification preferences. The settings above apply to the whole workspace.
• Web push (browser notifications).