Notifications

The Notifications API manages in-app notifications and push token registration for Firebase Cloud Messaging (FCM). All endpoints require authentication.

---

GET /v1/notifications

List notifications for the authenticated user, newest first.

Authentication: Bearer token required.

Request

GET /v1/notifications?page=1&per_page=20&unread=true
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Query Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 20)
unread	boolean	If true, only return unread notifications

Response

{
  "success": true,
  "data": [
    {
      "id": "01JN2XC2D3E4F5G6H7I8J9K0L1",
      "type": "payment_captured",
      "title": "Payment Received",
      "body": "You earned $16.00 from a call with Alex",
      "data": {
        "call_session_id": "01JN2X6M0P5H9SRBTXY8ZDKEFG",
        "amount": "16.00"
      },
      "read": false,
      "created_at": "2026-03-15T14:10:00Z"
    },
    {
      "id": "01JN2XD3E4F5G6H7I8J9K0L1M2",
      "type": "call_incoming",
      "title": "Incoming Call",
      "body": "Alex is waiting for you",
      "data": {
        "call_session_id": "01JN2X6M0P5H9SRBTXY8ZDKEFG"
      },
      "read": true,
      "created_at": "2026-03-15T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 15,
    "total_pages": 1
  }
}

Notification Types

Type	Description
call_incoming	Guest is waiting --- host should join
call_missed	Host did not join within threshold
payment_captured	Payment captured after call
payout_completed	Payout sent to bank
payout_failed	Payout to bank failed
follow_new	New follower
support_reply	Admin replied to support ticket
broadcast	Admin broadcast notification

---

GET /v1/notifications/unread-count

Get the count of unread notifications.

Authentication: Bearer token required.

GET /v1/notifications/unread-count
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Response

{
  "count": 3
}

---

PUT /v1/notifications/:id/read

Mark a single notification as read.

Authentication: Bearer token required.

PUT /v1/notifications/01JN2XC2D3E4F5G6H7I8J9K0L1/read
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Returns 204 No Content on success.

Errors

Code	Status	Description
not_found	404	Notification not found or does not belong to user

---

PUT /v1/notifications/read-all

Mark all notifications as read for the authenticated user.

Authentication: Bearer token required.

PUT /v1/notifications/read-all
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Returns 204 No Content on success.

---

Push Token Management

POST /v1/notifications/push-tokens

Register a device push token for FCM push notifications.

Authentication: Bearer token required.

POST /v1/notifications/push-tokens
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
Content-Type: application/json

{
  "token": "fcm_device_token_string",
  "platform": "ios"
}

Field	Type	Required	Description
token	string	Yes	FCM device registration token
platform	string	Yes	ios, android, or web

Response

HTTP/1.1 201 Created

{
  "id": "01JN2XE4F5G6H7I8J9K0L1M2N3",
  "token": "fcm_device_token_string",
  "platform": "ios",
  "created_at": "2026-03-15T10:00:00Z"
}

---

GET /v1/notifications/push-tokens

List all registered push tokens for the authenticated user.

Authentication: Bearer token required.

GET /v1/notifications/push-tokens
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

---

DELETE /v1/notifications/push-tokens/:id

Remove a push token (e.g., when signing out of a device).

Authentication: Bearer token required.

DELETE /v1/notifications/push-tokens/01JN2XE4F5G6H7I8J9K0L1M2N3
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Returns 204 No Content on success.

---

Code Examples

cURL

# List notifications
curl "https://api.vidivo.app/v1/notifications?per_page=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

# Get unread count
curl "https://api.vidivo.app/v1/notifications/unread-count" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

# Mark all as read
curl -X PUT "https://api.vidivo.app/v1/notifications/read-all" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

# Register push token
curl -X POST "https://api.vidivo.app/v1/notifications/push-tokens" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{"token":"fcm_token_here","platform":"web"}'

JavaScript

const API = 'https://api.vidivo.app/v1';

// Get unread count
const { count } = await fetch(`${API}/notifications/unread-count`, {
  headers: { Authorization: `Bearer ${accessToken}` },
}).then(r => r.json());

// Register FCM token (after getting token from Firebase SDK)
const fcmToken = await getToken(messaging, { vapidKey: 'your-vapid-key' });
await fetch(`${API}/notifications/push-tokens`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
  },
  body: JSON.stringify({ token: fcmToken, platform: 'web' }),
});

// Mark all as read
await fetch(`${API}/notifications/read-all`, {
  method: 'PUT',
  headers: { Authorization: `Bearer ${accessToken}` },
});