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.Send Notification to User ⭐
PRIMARY FUNCTION - Sends notifications to a user across all their devices via FCM/APNs.Schedule Notification
Schedule a notification to be sent at a specific future time.Cancel Scheduled Notification
Cancel a pending scheduled notification.Send Bulk Notification
Send notifications to multiple users efficiently with batching.Get User Device Tokens
Retrieve all active device tokens for a user.Send Test Notification
Send a test notification with debugging information.Debug User Notifications
Debug notification setup for troubleshooting.Get Notification Statistics
Retrieve comprehensive notification statistics.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.
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.
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.
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
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
