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.Native FCM token (Android) or APNs token (iOS)
Device platform
App version for tracking
Device information object with
deviceId, deviceName, and osVersionSend Notification to User ⭐
PRIMARY FUNCTION - Sends notifications to a user across all their devices via FCM/APNs.User ID to send notification to
Notification title
Notification body text
Optional data payload for deep linking and custom handling
Notification priority (default: “normal”)
Schedule Notification
Schedule a notification to be sent at a specific future time.User ID to send to
Notification title
Notification body
Unix timestamp for when to send
Optional data payload
Notification priority
Cancel Scheduled Notification
Cancel a pending scheduled notification.Scheduled notification ID to cancel
Send Bulk Notification
Send notifications to multiple users efficiently with batching.Array of user IDs to send to
Notification title
Notification body
Optional data payload
Batch size for processing (default: 50)
Get User Device Tokens
Retrieve all active device tokens for a user.User ID (defaults to authenticated user)
Send Test Notification
Send a test notification with debugging information.User ID to send test to
Custom title (default: ”🧪 Test Notification”)
Custom body (default: timestamp)
Debug User Notifications
Debug notification setup for troubleshooting.User ID to debug
Get Notification Statistics
Retrieve comprehensive notification statistics.Filter start date (Unix timestamp)
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:Firebase (FCM) Setup
Firebase (FCM) Setup
Required environment variables:Setup steps:
- Go to Firebase Console → Project Settings
- Generate a new private key for service account
- Copy the JSON content to
FCM_SERVICE_ACCOUNT - Set your project ID in
FCM_PROJECT_ID
Apple (APNs) Setup
Apple (APNs) Setup
Required environment variables:Setup steps:
- Go to Apple Developer → Keys
- Create a new APNs key
- Download the .p8 file and copy content to
APNS_PRIVATE_KEY - Set the key ID, team ID, and bundle ID
Error Handling
Token registration failed
Token registration failed
Status Code:
400User has no tokens
User has no tokens
Status Code:
404FCM/APNs delivery failed
FCM/APNs delivery failed
Status Code:
500This notification system is production-ready and handles millions of notifications daily. It includes automatic retry logic, token validation, and comprehensive error handling.
Debug & Testing
These functions live inconvex/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.
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.
The FCM device token to send to
Custom notification title (default: “Direct FCM Test”)
Custom notification body (default: “This is a direct FCM test notification”)
debugNotificationSystemInternal
Type:query (internal)
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.
The user ID to check
sendFCMNotificationDirect
Type:internalAction (Node.js runtime)
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
Array of FCM device tokens to send to
Notification title
Notification body text
Optional key-value data payload
FCM delivery priority
sendAPNsNotificationDirect
Type:internalAction (Node.js runtime)
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
Array of APNs device tokens to send to
Notification title
Notification body text
Optional key-value data payload (merged into the APNs payload alongside
aps)App badge count to display
Notification sound name (default: “default”)
