Skip to main content

​
Overview

The Push Notifications API allows you to send notifications to subscribers using configured push notification services (FCM, APNS, etc.). All endpoints are prefixed with /v2/push-notification.

​
Get Subscriber Authentication Token

Generate a JWT authentication token for a subscriber.
GET /v2/push-notification/subscriber-auth-token
curl -X GET "https://example.com:5443/LiveApp/rest/v2/push-notification/subscriber-auth-token?subscriberId=user123&timeoutSeconds=3600" \
  -H "Authorization: Bearer {jwt}"
​
subscriberId
string
required
Subscriber ID to generate token for
​
timeoutSeconds
integer
default:"3600"
Token validity duration in seconds (default: 1 hour)
​
success
boolean
Whether token generation succeeded
​
dataId
string
The generated JWT token
​
message
string
Description: “Token is available in dataId field”
Example Response: 
{
  "success": true,
  "dataId": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "message": "Token is available in dataId field"
}

​
Send Notification to Subscribers

Send a push notification to specific subscribers.
POST /v2/push-notification/subscribers
curl -X POST "https://example.com:5443/LiveApp/rest/v2/push-notification/subscribers?serviceName=fcm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {jwt}" \
  -d '{
    "subscribers": ["user123", "user456", "user789"],
    "jsonMessage": "{\"title\":\"New Stream\",\"body\":\"Your favorite streamer is live!\"}"
  }'
​
subscribers
string[]
required
Array of subscriber IDs to send notification to
​
jsonMessage
string
required
JSON-formatted notification message as a string
​
serviceName
string
Name of the push notification service to use. If not specified, uses the default service.
​
success
boolean
Whether notification was sent successfully
​
message
string
Result message or error description
Example Notification Message: 
{
  "title": "Stream Started",
  "body": "John Doe has started a new live stream",
  "data": {
    "streamId": "stream123",
    "action": "join_stream"
  }
}
The jsonMessage parameter must be a JSON string (not a JSON object). The API will parse it internally.

​
Send Notification to Topic

Send a push notification to all subscribers of a topic.
POST /v2/push-notification/topics/{topic}
curl -X POST "https://example.com:5443/LiveApp/rest/v2/push-notification/topics/sports?serviceName=fcm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {jwt}" \
  -d '{
    "title": "Live Match",
    "body": "Football match is starting now!",
    "streamId": "match123"
  }'
​
topic
string
required
Topic name to send notification to
​
title
string
Notification title
​
body
string
Notification message body
​
data
object
Additional data payload for the notification
​
serviceName
string
Name of the push notification service to use
​
success
boolean
Whether notification was sent successfully
​
message
string
Result message or error description
Example Request Body: 
{
  "title": "New Content Available",
  "body": "Check out the latest videos in Sports category",
  "data": {
    "category": "sports",
    "action": "open_category"
  },
  "imageUrl": "https://example.com/thumbnail.jpg"
}

​
Push Notification Services

​
Supported Services

Ant Media Server supports multiple push notification services:
  • FCM (Firebase Cloud Messaging) - For Android and iOS
  • APNS (Apple Push Notification Service) - For iOS
  • Custom notification services via plugins

​
Configuration

Push notification services must be configured in the application settings before use. Each service requires specific credentials: FCM Configuration:
  • Service account JSON file
  • Project ID
APNS Configuration:
  • Certificate file
  • Private key
  • Team ID
  • Bundle ID

​
Service Selection

If multiple notification services are configured:
  • Without serviceName parameter: Uses the default/first configured service
  • With serviceName parameter: Uses the specified service
# Use default service
curl -X POST ".../subscribers"

# Use specific service
curl -X POST ".../subscribers?serviceName=fcm"
curl -X POST ".../subscribers?serviceName=apns"

​
Notification Message Format

​
Standard Fields

Most push notification services support these standard fields:
​
title
string
Notification title displayed prominently
​
body
string
Main notification message text
​
imageUrl
string
URL to an image to display in the notification
​
data
object
Custom data payload passed to the app

​
FCM-Specific Fields

For Firebase Cloud Messaging, you can include: 
{
  "title": "New Message",
  "body": "You have a new message",
  "data": {
    "messageId": "msg123",
    "senderId": "user456"
  },
  "android": {
    "priority": "high",
    "notification": {
      "sound": "default",
      "color": "#FF0000"
    }
  },
  "apns": {
    "payload": {
      "aps": {
        "badge": 1,
        "sound": "default"
      }
    }
  }
}

​
Use Cases

​
Notify Subscribers When Stream Starts

// When a stream goes live
fetch('https://example.com:5443/LiveApp/rest/v2/push-notification/subscribers', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + jwtToken
  },
  body: JSON.stringify({
    subscribers: ['user1', 'user2', 'user3'],
    jsonMessage: JSON.stringify({
      title: 'Stream is Live!',
      body: 'Your favorite streamer just went live',
      data: {
        streamId: 'stream123',
        action: 'join_stream'
      }
    })
  })
});

​
Notify Topic Subscribers

// Notify all subscribers of a sports topic
fetch('https://example.com:5443/LiveApp/rest/v2/push-notification/topics/sports', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + jwtToken
  },
  body: JSON.stringify({
    title: 'Live Match Starting',
    body: 'Football: Team A vs Team B',
    data: {
      streamId: 'match123',
      sport: 'football'
    },
    imageUrl: 'https://example.com/match-thumbnail.jpg'
  })
});

​
Error Handling

​
Common Errors

Invalid JSON Message: 
{
  "success": false,
  "message": "JSON content cannot be parsed. Make sure JSON content is in correct format"
}
Blank Subscriber ID: 
{
  "success": false,
  "message": "subscriberId is blank. Please give subscriberId as query parameter"
}
Service Not Configured: 
{
  "success": false,
  "message": "Push notification service 'serviceName' is not configured"
}

​
Best Practices

  1. Validate JSON - Ensure your notification message is valid JSON before sending
  2. Handle errors gracefully - Check the success field in responses
  3. Batch notifications - Send to multiple subscribers in one request when possible
  4. Use topics - For broadcasting to many users, use topic-based notifications
  5. Include data payload - Add context data so the app can handle the notification appropriately

​
Integration with Subscribers

Push notifications work in conjunction with the Subscriber API. To enable notifications for a subscriber:
  1. Add subscriber to a stream using /v2/broadcasts/{id}/subscribers
  2. Configure subscriber’s push notification token/device ID
  3. Send notifications when events occur (stream start, messages, etc.)
See the Broadcasts API - Subscribers section for subscriber management.

Build docs developers (and LLMs) love

Get started for freeTalk to us