Notifications (User-wide)

Here you can interact with the actual notifications send to the users. This section deals with user-wide notifications - meaning you can list & query notifications for a given user ID. If you would like to query notifications for the whole project, refer to the previous section - Notifications API (Project-wide).

List notifications paginated

GET {base_uri}/project/{project_id}/user/{user_id}/notifications

Get a list of notifications sent to this specific user. Sorted by default in reverse chronological order (latest notifications first).

Example response

GET https://belltastic.com/api/v1/project/1/user/9/notifications

{
  "data": [
    {
      "id": "9505f167-c4d5-4191-ba6b-08e47f6686c3",
      "project_id": 1,
      "user_id": 9,
      "icon": "https:\/\/via.placeholder.com\/80x80.png\/000033?text=consequatur",
      "title": "qui corporis consequatur in",
      "body": "Et enim eum placeat saepe molestias iure. Quo impedit qui ratione repellat quam. Officiis ad est dolorem debitis possimus sint molestiae et.",
      "category": "comment",
      "action_url": null,
      "seen_at": null,
      "read_at": null,
      "created_at": "2021-11-24T20:27:28+00:00",
      "deleted_at": null
    },
    {
      "id": "9505f167-c488-4a73-8515-fa4d0465a6d2",
      "project_id": 1,
      "user_id": 9,
      "icon": "https:\/\/via.placeholder.com\/80x80.png\/0033cc?text=dolorem",
      "title": "voluptates aspernatur dolorem possimus",
      "body": "Rerum eum voluptatum iusto nihil. Reprehenderit eum fugiat maiores.",
      "category": "like",
      "action_url": null,
      "seen_at": null,
      "read_at": null,
      "created_at": "2021-11-12T00:02:46+00:00",
      "deleted_at": null
    },
    ...
  ],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": "https:\/\/belltastic.com\/api\/v1\/project\/1\/user\/075817ef-c337-33a4-a1e3-10f233647816\/notifications?per_page=10&order=desc&cursor=eyJpZCI6Ijk1MDVmMTY3LWMyMmEtNGRkZS05NTRiLWJjMGVjMjkzNmFkNCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
  },
  "meta": {
    "path": "https:\/\/belltastic.com\/api\/v1\/project\/1\/user\/075817ef-c337-33a4-a1e3-10f233647816\/notifications",
    "per_page": 10
  }
}

Show notification

GET {base_uri}/project/{project_id}/user/{user_id}/notification/{id}

Get a single notification from the user.

Example response

GET https://belltastic.com/api/v1/project/1/user/9/notification/9505f167-c488-4a73-8515-fa4d0465a6d2

{
  "id": "9505f167-c488-4a73-8515-fa4d0465a6d2",
  "project_id": 1,
  "user_id": 9,
  "icon": "https:\/\/via.placeholder.com\/80x80.png\/0033cc?text=dolorem",
  "title": "voluptates aspernatur dolorem possimus",
  "body": "Rerum eum voluptatum iusto nihil. Reprehenderit eum fugiat maiores.",
  "category": "like",
  "action_url": null,
  "seen_at": null,
  "read_at": null,
  "created_at": "2021-11-12T00:02:46+00:00",
  "deleted_at": null
}

Example response (404 - Not Found)

GET https://belltastic.com/api/v1/project/1/user/9/notification/INVALID-ID

{
  "message": "Notification not found."
}

Create notification

POST {base_uri}/project/{project_id}/user/{user_id}/notifications

Create and send a new notification for the user.

Attribute	Type	Required?	Description
title	string	Yes	Short title of the notification. Displayed in bigger, bolder text. Max 255 characters
body	string	No	Longer text for the notification used to explain to the user in more detail about the event. Max 10,000 characters
icon	string	No	URL to an image (PNG/JPEG/SVG/etc) that will be displayed as the icon of the notification
category	string	No	Optional category name for this notification. Users will be able to configure their Notification Component to mute/ignore certain categories
action_url	string	No	A link that gets visited when a user clicks on the notification

Example response (201 - Created)

Request: POST https://belltastic.com/api/v1/project/1/user/9/notifications with body

{
  "title": "Sample notification title. Short and simple.",
  "body": "Here goes a longer notification body that will be displayed in smaller text. Use this to provide more information to the user about the event.",
  "action_url": "https://belltastic.com/docs"
}

Response:

{
  "message": "Notification created.",
  "data": {
    "id": "95165062-d0c5-4160-a417-df029720e13b",
    "project_id": 1,
    "user_id": 9,
    "icon": null,
    "title": "Sample notification title. Short and simple.",
    "body": "Here goes a longer notification body that will be displayed in smaller text. Use this to provide more information to the user about the event.",
    "category": null,
    "action_url": "https:\/\/belltastic.com\/docs",
    "seen_at": null,
    "read_at": null,
    "created_at": "2021-12-11T13:51:44+00:00",
    "deleted_at": null
  }
}

Example response (422 - Validation Errors)

Request: POST https://belltastic.com/api/v1/project/1/user/1/notifications with body

{}

Response:

{
  "message": "The given data was invalid.",
  "errors": {
    "title": [
      "The title field is required."
    ]
  }
}

Example response (404 - Not Found)

Happens when you're trying to create a notification for a user that does not yet exist.

{
  "message": "User not found."
}

Update notification

Notifications cannot be updated. If you made a mistake in the title, body, actions, etc - please destroy the incorrect notification and create a new one.

The only valid state changes for existing notifications are listed below:

Mark as seen
Mark as read
Mark as unread

Mark notification as <seen>

POST {base_uri}/project/{project_id}/user/{user_id}/notification/{id}/seen

Updates the notification as "seen". It will have no effect if it has already been seen before.

Example response (200 - OK)

POST https://belltastic.com/api/v1/project/1/user/9/notification/9505f167-c3ef-4c7f-af0f-7c42b9de5f15/seen

{
  "message": "Notification updated.",
  "data": {
    "id": "9505f167-c3ef-4c7f-af0f-7c42b9de5f15",
    "project_id": 1,
    "user_id": 9,
    "icon": "https:\/\/via.placeholder.com\/80x80.png\/000044?text=non",
    "title": "iste consequatur voluptas in",
    "body": "Rerum fuga unde repellendus et deleniti aliquam. Est amet sint ex voluptatem voluptates architecto. Aperiam ut soluta architecto sequi a. Sapiente perferendis alias inventore eveniet molestiae.",
    "category": "comment",
    "action_url": null,
    "seen_at": "2021-12-11T09:04:27+00:00",
    "read_at": null,
    "created_at": "2021-11-26T21:39:27+00:00",
    "deleted_at": null
  }
}

Example response (404 - Not Found)

{
  "message": "Notification not found."
}

Mark notification as <read>

POST {base_uri}/project/{project_id}/user/{user_id}/notification/{id}/read

Updates the notification as "read". It will have no effect if it has already been read before.

Example response (200 - OK)

POST https://belltastic.com/api/v1/project/1/user/9/notification/9505f167-c3ef-4c7f-af0f-7c42b9de5f15/read

{
  "message": "Notification updated.",
  "data": {
    "id": "9505f167-c3ef-4c7f-af0f-7c42b9de5f15",
    "project_id": 1,
    "user_id": 9,
    "icon": "https:\/\/via.placeholder.com\/80x80.png\/000044?text=non",
    "title": "iste consequatur voluptas in",
    "body": "Rerum fuga unde repellendus et deleniti aliquam. Est amet sint ex voluptatem voluptates architecto. Aperiam ut soluta architecto sequi a. Sapiente perferendis alias inventore eveniet molestiae.",
    "category": "comment",
    "action_url": null,
    "seen_at": null,
    "read_at": "2021-12-11T09:31:01+00:00",
    "created_at": "2021-11-26T21:39:27+00:00",
    "deleted_at": null
  }
}

Example response (404 - Not Found)

{
  "message": "Notification not found."
}

Mark notification as <unread>

DELETE {base_uri}/project/{project_id}/user/{user_id}/notification/{id}/read

Removes the "read" status from the notification, making it as if it was never read.

Example response (200 - OK)

DELETE https://belltastic.com/api/v1/project/1/user/9/notification/9505f167-c3ef-4c7f-af0f-7c42b9de5f15/read

{
  "message": "Notification updated.",
  "data": {
    "id": "9505f167-c3ef-4c7f-af0f-7c42b9de5f15",
    "project_id": 1,
    "user_id": 9,
    "icon": "https:\/\/via.placeholder.com\/80x80.png\/000044?text=non",
    "title": "iste consequatur voluptas in",
    "body": "Rerum fuga unde repellendus et deleniti aliquam. Est amet sint ex voluptatem voluptates architecto. Aperiam ut soluta architecto sequi a. Sapiente perferendis alias inventore eveniet molestiae.",
    "category": "comment",
    "action_url": null,
    "seen_at": null,
    "read_at": null,
    "created_at": "2021-11-26T21:39:27+00:00",
    "deleted_at": null
  }
}

Example response (404 - Not Found)

{
  "message": "Notification not found."
}

Mark all notifications as <read>

POST {base_uri}/project/{project_id}/user/{user_id}/notifications/read

Marks all the user's notifications as read. Previously read notifications will not be affected.

Example response

POST https://belltastic.com/api/v1/project/1/user/9/notifications/read

{
  "message": "Notifications updated.",
  "notifications_updated": 54,
  "read_at": "2021-12-11T09:42:18+00:00"
}

Archive notification

PUT {base_uri}/project/{project_id}/user/{user_id}/notification/{id}/archive

Archive (soft-delete) a single notification from the user. It will disappear from the user's notification box.

If the notification was archived already, it does nothing extra - the deleted_at timestamp does not change.

Example response

PUT https://belltastic.com/api/v1/project/1/user/9/notification/9505f167-c488-4a73-8515-fa4d0465a6d2/archive

{
  "message": "Notification archived.",
  "data": {
    "id": "9505f167-c488-4a73-8515-fa4d0465a6d2",
    "project_id": 1,
    "user_id": 9,
    "icon": "https:\/\/via.placeholder.com\/80x80.png\/0033cc?text=dolorem",
    "title": "voluptates aspernatur dolorem possimus",
    "body": "Rerum eum voluptatum iusto nihil. Reprehenderit eum fugiat maiores.",
    "category": "like",
    "action_url": null,
    "seen_at": null,
    "read_at": null,
    "created_at": "2021-11-12T00:02:46+00:00",
    "deleted_at": "2021-12-11T06:56:22+00:00"
  }
}

Destroy notification

DELETE {base_uri}/project/{project_id}/user/{user_id}/notification/{id}

Permanently destroy a single notification from the user. It will disappear from the user's notification box.

DANGER

Data cannot be retrieved after the notification has been destroyed as it will be permanently deleted from all our servers.

Example response

DELETE https://belltastic.com/api/v1/project/1/user/9/notification/9505f167-c488-4a73-8515-fa4d0465a6d2

{
  "message": "Notification deleted."
}

# Notifications (User-wide)

# List notifications paginated

# Show notification

# Create notification

# Update notification

# Mark notification as <seen>

# Mark notification as <read>

# Mark notification as <unread>

# Mark all notifications as <read>

# Archive notification

# Destroy notification

Notifications (User-wide)

List notifications paginated

Show notification

Create notification

Update notification

Mark notification as <seen>

Mark notification as <read>

Mark notification as <unread>

Mark all notifications as <read>

Archive notification

Destroy notification