Batchmates

Notifications

Stay informed about donation confirmations, campaign updates, and important announcements through the notifications system.

The Notification Model

Notifications use Laravel's built-in notification system with the following structure:

Properties

  • Name
    id
    Type
    uuid
    Description

    Unique identifier for the notification

  • Name
    type
    Type
    string
    Description

    Notification class type (e.g., "App\Notifications\CampaignCreated")

  • Name
    notifiable_type
    Type
    string
    Description

    Type of entity receiving notification (usually "App\Models\User")

  • Name
    notifiable_id
    Type
    integer
    Description

    ID of the entity receiving notification

  • Name
    data
    Type
    json
    Description

    Notification payload containing title, message, and action data

  • Name
    read_at
    Type
    timestamp | null
    Description

    When notification was read (null if unread)

  • Name
    created_at
    Type
    timestamp
    Description

    When notification was created

Notification Data Structure

The data field typically contains:

{
  "title": "Donation Successful",
  "message": "Your ₱1,000 donation to Engineering Scholarship Fund was successful.",
  "action_url": "/campaigns/5",
  "action_text": "View Campaign",
  "type": "donation_success"
}
GET/api/v1/notifications

List Notifications

Retrieves a paginated list of notifications for the authenticated user, sorted by most recent first.

Authentication: Required

Query Parameters

  • Name
    page
    Type
    integer
    Description

    Page number (default: 1)

  • Name
    per_page
    Type
    integer
    Description

    Items per page (default: 15)

  • Name
    unread_only
    Type
    boolean
    Description

    Show only unread notifications (default: false)

Request

curl -G https://batchmates-v2.revlv.com/api/v1/notifications \
  -H "Authorization: Bearer {token}" \
  -d "per_page=20"

Response

{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "9d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
        "type": "App\\Notifications\\DonationSuccessful",
        "data": {
          "title": "Donation Successful",
          "message": "Your ₱1,000 donation to Engineering Scholarship Fund was successful.",
          "action_url": "/campaigns/5",
          "action_text": "View Campaign",
          "donation_id": 45
        },
        "read_at": null,
        "created_at": "2024-02-06T10:30:00.000000Z"
      },
      {
        "id": "8c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
        "type": "App\\Notifications\\CampaignUpdate",
        "data": {
          "title": "Campaign Goal Reached!",
          "message": "Engineering Scholarship Fund has reached its ₱100,000 goal!",
          "action_url": "/campaigns/5",
          "campaign_id": 5
        },
        "read_at": "2024-02-05T14:20:00.000000Z",
        "created_at": "2024-02-05T12:00:00.000000Z"
      }
    ],
    "pagination": {
      "total": 45,
      "per_page": 20,
      "current_page": 1,
      "last_page": 3,
      "from": 1,
      "to": 20
    },
    "unread_count": 5
  }
}

Request (Unread Only)

curl -G https://batchmates-v2.revlv.com/api/v1/notifications \
  -H "Authorization: Bearer {token}" \
  -d "unread_only=true"
POST/api/v1/notifications/{id}/read

Mark as Read

Marks a specific notification as read by setting the read_at timestamp.

Authentication: Required

Path Parameters

  • Name
    id
    Type
    uuid
    Description

    The notification ID

Request

curl -X POST https://batchmates-v2.revlv.com/api/v1/notifications/9d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a/read \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Notification marked as read",
  "data": {
    "id": "9d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
    "type": "App\\Notifications\\DonationSuccessful",
    "data": {
      "title": "Donation Successful",
      "message": "Your ₱1,000 donation was successful."
    },
    "read_at": "2024-02-06T11:00:00.000000Z",
    "created_at": "2024-02-06T10:30:00.000000Z"
  }
}

Error (Not Found)

{
  "message": "No query results for model [Illuminate\\Notifications\\DatabaseNotification]"
}
POST/api/v1/notifications/mark-all-read

Mark All as Read

Marks all unread notifications as read for the authenticated user.

Authentication: Required

Request

curl -X POST https://batchmates-v2.revlv.com/api/v1/notifications/mark-all-read \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Marked 5 notification(s) as read",
  "data": {
    "marked_count": 5
  }
}

Response (No Unread)

{
  "success": true,
  "message": "Marked 0 notification(s) as read",
  "data": {
    "marked_count": 0
  }
}
GET/api/v1/notifications/unread-count

Get Unread Count

Retrieves the count of unread notifications. Useful for displaying notification badges in the UI.

Authentication: Required

Request

curl https://batchmates-v2.revlv.com/api/v1/notifications/unread-count \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "unread_count": 5
  }
}
DELETE/api/v1/notifications/{id}

Delete Notification

Permanently deletes a specific notification.

Authentication: Required

Path Parameters

  • Name
    id
    Type
    uuid
    Description

    The notification ID to delete

Request

curl -X DELETE https://batchmates-v2.revlv.com/api/v1/notifications/9d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Notification deleted"
}

Error (Not Found)

{
  "message": "No query results for model [Illuminate\\Notifications\\DatabaseNotification]"
}
DELETE/api/v1/notifications

Delete All Notifications

Permanently deletes all notifications for the authenticated user.

Authentication: Required

Request

curl -X DELETE https://batchmates-v2.revlv.com/api/v1/notifications \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Deleted 45 notification(s)",
  "data": {
    "deleted_count": 45
  }
}

Response (No Notifications)

{
  "success": true,
  "message": "Deleted 0 notification(s)",
  "data": {
    "deleted_count": 0
  }
}

Notification Types

Common notification types you'll receive:

Donation Related

  • Name
    DonationSuccessful
    Description

    Your donation was processed successfully

  • Name
    DonationFailed
    Description

    Payment processing failed

  • Name
    RecurringDonationCharged
    Description

    Monthly subscription payment processed

  • Name
    SubscriptionPaymentFailed
    Description

    Recurring donation payment failed

Campaign Related

  • Name
    CampaignCreated
    Description

    New campaign submitted for your institution

  • Name
    CampaignApproved
    Description

    Your campaign was approved

  • Name
    CampaignUpdate
    Description

    Campaign milestone or update

  • Name
    CampaignGoalReached
    Description

    Campaign reached its fundraising goal

Account Related

  • Name
    WelcomeNotification
    Description

    Welcome message for new users

  • Name
    PasswordChanged
    Description

    Your password was updated

  • Name
    ProfileUpdated
    Description

    Your profile was modified

Notification Data Structure

Each notification's data field contains structured information:

Standard Fields

{
  "title": "Short notification title",
  "message": "Detailed notification message",
  "action_url": "/campaigns/5",
  "action_text": "View Campaign",
  "type": "donation_success"
}

Donation Notification

{
  "title": "Donation Successful",
  "message": "Your ₱1,000 donation to Engineering Scholarship Fund was successful.",
  "action_url": "/donations/45",
  "action_text": "View Receipt",
  "donation_id": 45,
  "campaign_id": 5,
  "amount": "1000.00"
}

Campaign Update

{
  "title": "Campaign Update",
  "message": "Engineering Scholarship Fund has reached 75% of its goal!",
  "action_url": "/campaigns/5",
  "campaign_id": 5,
  "current_amount": "75000.00",
  "goal_amount": "100000.00"
}

Read vs Unread Status

Notifications track read status through the read_at timestamp:

{
  "read_at": null  // Unread
}

{
  "read_at": "2024-02-06T11:00:00.000000Z"  // Read
}

Best Practices

  1. Display unread notifications prominently (bold text, badge)
  2. Mark as read when user views the notification
  3. Show unread count in navigation bar
  4. Sort by newest first (created_at descending)

Polling for New Notifications

To check for new notifications periodically:

// Check every 30 seconds
setInterval(async () => {
  const response = await fetch(
    'https://batchmates-v2.revlv.com/api/v1/notifications/unread-count',
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  const data = await response.json();
  updateBadge(data.data.unread_count);
}, 30000);

Recommendation: Use 30-60 second intervals to balance real-time updates with server load.

Pagination

Notifications are paginated for performance:

{
  "pagination": {
    "total": 45,
    "per_page": 15,
    "current_page": 1,
    "last_page": 3,
    "from": 1,
    "to": 15
  }
}

Use the page parameter to load additional pages:

curl -G https://batchmates-v2.revlv.com/api/v1/notifications \
  -H "Authorization: Bearer {token}" \
  -d "page=2"

Error Responses

  • Name
    401 Unauthorized
    Description

    Not authenticated or token expired

  • Name
    404 Not Found
    Description

    Notification does not exist or doesn't belong to user

Unauthorized

{
  "message": "Unauthenticated."
}

Not Found

{
  "message": "No query results for model [Illuminate\\Notifications\\DatabaseNotification]"
}

Was this page helpful?