Send Push Notification

This endpoint allows administrators to send push notifications to users' mobile devices. Notifications can be sent immediately or scheduled for a future date, and can target specific user groups within a platform.

Endpoint

• URL: /api/push-notifications
• Method: POST
• Authentication: Required (Admin access)

Request Body

Parameter	Type	Required	Default	Description
GroupId	integer	No	-	The ID of the group to send the notification to (if omitted, sends to all users)
PlatformId	integer	Yes	-	The ID of the platform
title	string	No	"Default Title"	The title of the notification
message	string	No	"Default Message"	The message content of the notification
scheduledFor	string (ISO date)	No	-	Date and time to send the notification (if not provided, sends immediately)
ContentId	integer	No	-	ID of content to link (mutually exclusive with url)
url	string (URL)	No	-	External URL to open (mutually exclusive with ContentId)
parameterData	string (JSON)	No	""	JSON string with additional data for the mobile app (auto-populated for content/url)
destinationPage	string	No	"Settings"	The page to navigate to (auto-set to "PostView" for content, "ExternalLink" for URLs)
recipients	array of integers	No	[]	Array of user IDs to receive the notification (if empty, sends to all users in the group)

Validation Rules

• ContentId and url are mutually exclusive - only one can be provided per notification
• If url is provided, it must be a valid URL format starting with http:// or https://
• If ContentId is provided, the content must exist and be accessible to the selected group
• When ContentId is set, the backend automatically sets destinationPage to "PostView" and includes contentId in parameterData
• When url is set, the backend automatically sets destinationPage to "ExternalLink" and includes externalUrl in parameterData

Response

Success Response

• Code: 200 OK
• Content: "Notification sent"

Error Response

• Code: 400 Bad Request
• Content:

{
  "error": "Something went wrong"
}

Notes

• Notifications are delivered through Firebase Cloud Messaging to mobile devices
• If scheduledFor is provided, the notification will be queued and sent at the specified time
• The parameterData field can contain any JSON data needed by the mobile app for deep linking
• The destinationPage field should match a valid page name in the mobile app
• For large groups, recipients are processed in batches of 500 users
• If the platform is not connected to a Firebase project, the notification will be created but not delivered

Example

External Link Notification (Zoom Meeting)

curl -X POST "https://api.example.com/api/push-notifications" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "PlatformId": 789,
    "title": "Live Session Starting Soon",
    "message": "Join us on Zoom in 10 minutes!",
    "url": "https://zoom.us/j/123456789?pwd=abc123"
  }'

Content Link Notification

curl -X POST "https://api.example.com/api/push-notifications" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": 456,
    "PlatformId": 789,
    "title": "New Video Available",
    "message": "Check out our latest tutorial!",
    "ContentId": 12345
  }'

Immediate Notification to All Users (No Link)

curl -X POST "https://api.example.com/api/push-notifications" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "PlatformId": 789,
    "title": "Platform Update",
    "message": "We've added new features to improve your experience!"
  }'

Scheduled Notification to Specific Users

curl -X POST "https://api.example.com/api/push-notifications" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": 456,
    "PlatformId": 789,
    "title": "Reminder: Upcoming Event",
    "message": "Don't forget about tomorrow's live session!",
    "scheduledFor": "2023-11-20T18:00:00.000Z",
    "ContentId": 789,
    "recipients": [1001, 1002, 1003]
  }'