Push Notifications API

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}"

string

required

Subscriber ID to generate token for

integer

default:"3600"

Token validity duration in seconds (default: 1 hour)

boolean

Whether token generation succeeded

string

The generated JWT token

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!\"}"
  }'

string[]

required

Array of subscriber IDs to send notification to

string

required

JSON-formatted notification message as a string

string

Name of the push notification service to use. If not specified, uses the default service.

boolean

Whether notification was sent successfully

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"
  }'

string

required

Topic name to send notification to

string

Notification title

string

Notification message body

object

Additional data payload for the notification

string

Name of the push notification service to use

boolean

Whether notification was sent successfully

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:

string

Notification title displayed prominently

string

Main notification message text

string

URL to an image to display in the notification

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

Validate JSON - Ensure your notification message is valid JSON before sending
Handle errors gracefully - Check the success field in responses
Batch notifications - Send to multiple subscribers in one request when possible
Use topics - For broadcasting to many users, use topic-based notifications
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:

Add subscriber to a stream using /v2/broadcasts/{id}/subscribers
Configure subscriber’s push notification token/device ID
Send notifications when events occur (stream start, messages, etc.)

See the Broadcasts API - Subscribers section for subscriber management.

REST API

WebRTC API

Data Models

Overview

Get Subscriber Authentication Token

Send Notification to Subscribers

Send Notification to Topic

Push Notification Services

Supported Services

Configuration

Service Selection

Notification Message Format

Standard Fields

FCM-Specific Fields

Use Cases

Notify Subscribers When Stream Starts

Notify Topic Subscribers

Error Handling

Common Errors

Best Practices

Integration with Subscribers

​Overview

​Get Subscriber Authentication Token

​Send Notification to Subscribers

​Send Notification to Topic

​Push Notification Services

​Supported Services

​Configuration

​Service Selection

​Notification Message Format

​Standard Fields

​FCM-Specific Fields

​Use Cases

​Notify Subscribers When Stream Starts

​Notify Topic Subscribers

​Error Handling

​Common Errors

​Best Practices

​Integration with Subscribers

Overview

Get Subscriber Authentication Token

Send Notification to Subscribers

Send Notification to Topic

Push Notification Services

Supported Services

Configuration

Service Selection

Notification Message Format

Standard Fields

FCM-Specific Fields

Use Cases

Notify Subscribers When Stream Starts

Notify Topic Subscribers

Error Handling

Common Errors

Best Practices

Integration with Subscribers