Skip to main content
Important: This system uses ONLY Firebase Cloud Messaging (FCM) and Apple Push Notification Service (APNs). Expo push service has been completely removed for full control and production reliability.

Overview

The Notifications API provides a comprehensive push notification system built specifically for production environments. It supports direct FCM and APNs integration, scheduled notifications, bulk messaging, and advanced debugging tools. Location: convex/shared/notifications.ts & convex/shared/notificationActions.ts

Key Features

FCM/APNs Direct

Direct integration with Firebase and Apple push services - no third-party dependencies

Scheduled Notifications

Send notifications at specific future times with automatic scheduling

Bulk Messaging

Efficiently send notifications to multiple users with batching and rate limiting

Advanced Debugging

Comprehensive debugging tools for troubleshooting delivery issues

Record Native Device Token ⭐

PRIMARY FUNCTION - Records a native device token (FCM/APNs) for direct push notifications.
deviceToken
string
required
Native FCM token (Android) or APNs token (iOS)
platform
'ios' | 'android'
required
Device platform
appVersion
string
App version for tracking
deviceInfo
object
Device information object with deviceId, deviceName, and osVersion

Send Notification to User ⭐

PRIMARY FUNCTION - Sends notifications to a user across all their devices via FCM/APNs.
userId
string
required
User ID to send notification to
title
string
required
Notification title
body
string
required
Notification body text
data
Record<string, string>
Optional data payload for deep linking and custom handling
priority
'high' | 'normal'
Notification priority (default: “normal”)

Schedule Notification

Schedule a notification to be sent at a specific future time.
userId
string
required
User ID to send to
title
string
required
Notification title
body
string
required
Notification body
scheduledTime
number
required
Unix timestamp for when to send
data
Record<string, string>
Optional data payload
priority
'high' | 'normal'
Notification priority

Cancel Scheduled Notification

Cancel a pending scheduled notification.
notificationId
Id<'scheduledNotifications'>
required
Scheduled notification ID to cancel

Send Bulk Notification

Send notifications to multiple users efficiently with batching.
userIds
Array<string>
required
Array of user IDs to send to
title
string
required
Notification title
body
string
required
Notification body
data
Record<string, string>
Optional data payload
batchSize
number
Batch size for processing (default: 50)

Get User Device Tokens

Retrieve all active device tokens for a user.
userId
string
User ID (defaults to authenticated user)

Send Test Notification

Send a test notification with debugging information.
userId
string
required
User ID to send test to
title
string
Custom title (default: ”🧪 Test Notification”)
body
string
Custom body (default: timestamp)

Debug User Notifications

Debug notification setup for troubleshooting.
userId
string
required
User ID to debug

Get Notification Statistics

Retrieve comprehensive notification statistics.
startDate
number
Filter start date (Unix timestamp)
endDate
number
Filter end date (Unix timestamp)

Notification Types

The system supports various notification types:

Order Status

Order updates, confirmations, and delivery notifications

Payment

Payment confirmations, failures, and refund notifications

Delivery

Delivery tracking, ETA updates, and completion notifications

Promotions

Marketing campaigns, discounts, and special offers

Announcements

System updates, maintenance notices, and feature releases

Store Status

Store approval, rejection, and operational status changes

Complete Integration Example

Here’s a complete notification integration:

Environment Setup

To use FCM/APNs notifications, configure these environment variables:
Required environment variables:
Setup steps:
  1. Go to Firebase Console → Project Settings
  2. Generate a new private key for service account
  3. Copy the JSON content to FCM_SERVICE_ACCOUNT
  4. Set your project ID in FCM_PROJECT_ID
Required environment variables:
Setup steps:
  1. Go to Apple Developer → Keys
  2. Create a new APNs key
  3. Download the .p8 file and copy content to APNS_PRIVATE_KEY
  4. Set the key ID, team ID, and bundle ID

Error Handling

Status Code: 400
Status Code: 404
Status Code: 500
This notification system is production-ready and handles millions of notifications daily. It includes automatic retry logic, token validation, and comprehensive error handling.
Always test notifications in both development and production environments, as token formats and delivery behavior can differ between environments.

Debug & Testing

These functions live in convex/shared/notificationDebug.ts and convex/shared/notificationActions.ts. They provide low-level debugging, direct platform testing, and internal send capabilities for the notification system.

debugNotificationSystem

Type: query Comprehensive health check for a user’s notification setup. Returns device tokens, recent notification history, environment configuration status, and actionable recommendations.
userId
string
required
The user ID to inspect

testSendNotification

Type: action (requires authentication) Sends a test notification to the currently authenticated user across all their registered devices. Useful for verifying end-to-end notification delivery without needing to specify a user ID.
This function requires authentication. It automatically sends to the calling user’s devices.

testFCMDirect

Type: action (requires authentication) Manually test FCM delivery by sending a notification to a specific FCM device token. Bypasses user lookup and sends directly to the provided token. Useful for isolating whether an FCM token is valid and reachable.
fcmToken
string
required
The FCM device token to send to
title
string
Custom notification title (default: “Direct FCM Test”)
body
string
Custom notification body (default: “This is a direct FCM test notification”)

debugNotificationSystemInternal

Type: query (internal)
This is an internal function intended for use by other server-side actions. It is not directly callable from client code.
Lightweight internal version of debugNotificationSystem. Returns a minimal summary of a user’s device token status for use in server-side logic and other actions.
userId
string
required
The user ID to check

sendFCMNotificationDirect

Type: internalAction (Node.js runtime)
This is an internal action that runs in the Node.js runtime. It is not directly callable from client code. It is used internally by testFCMDirect and the main notification dispatch system.
Sends push notifications to one or more Android devices via the Firebase Cloud Messaging (FCM) v1 API. Handles OAuth 2.0 token exchange using the configured service account and sends to each device token individually. Requires environment variables: FCM_SERVICE_ACCOUNT, FCM_PROJECT_ID
deviceTokens
Array<string>
required
Array of FCM device tokens to send to
title
string
required
Notification title
body
string
required
Notification body text
data
Record<string, string>
Optional key-value data payload
priority
'high' | 'normal'
FCM delivery priority

sendAPNsNotificationDirect

Type: internalAction (Node.js runtime)
This is an internal action that runs in the Node.js runtime. It is not directly callable from client code. It is used internally by the main notification dispatch system for iOS delivery.
Sends push notifications to one or more iOS devices via the Apple Push Notification service (APNs). Generates a JWT for APNs authentication and sends to each device token individually. Automatically selects the sandbox or production APNs endpoint based on the APNS_ENVIRONMENT variable. Requires environment variables: APNS_KEY_ID, APNS_TEAM_ID, APNS_PRIVATE_KEY, IOS_BUNDLE_ID, APNS_ENVIRONMENT
deviceTokens
Array<string>
required
Array of APNs device tokens to send to
title
string
required
Notification title
body
string
required
Notification body text
data
Record<string, string>
Optional key-value data payload (merged into the APNs payload alongside aps)
badge
number
App badge count to display
sound
string
Notification sound name (default: “default”)