Screen Notifications

Screen Notification informs the user about new interactions they are concerned with. The new ones are displayed into the “bubble” of the WordPress Admin Toolbar and all of them are listed within the user’s profile notifications page.

Note: The Notifications component is an optional one. This means the notifications endpoints will only be available if the component is active on the community site.

Schema Schema

The schema defines all the fields that exist for a notification object.

id

integer
A unique numeric ID for the notification.
Read only
Context: viewedit
user_id

integer
The ID of the user the notification is addressed to.
Default: logged in user ID
Context: view, edit
item_id

integer
The ID of the item associated with the notification.
Context: viewedit
secondary_item_id

integer
The ID of the secondary item associated with the notification.
Context: viewedit
component

string
The name of the BuddyPress component the notification relates to.
Context: viewedit
action

string
The name of the component’s action the notification is about.
Context: viewedit
date

string,
date-time
The date the notification was created, in the site’s timezone.
Context: viewedit
is_new

integer
Whether it’s a new notification or not.
Default: 1
Context: viewedit

Top ↑

List Screen Notifications for a specific user List Screen Notifications for a specific user

Arguments Arguments

NameTypeDescription
contextstringScope under which the request is made; determines fields present in response.
Default: view
One of: view, edit
pageintegerCurrent page of the collection.
Default: 1
per_pageintegerMaximum number of notifications to be returned in result set.
Default: 10
order_by

stringName of the field to order the notifications to.
Default: id
One of: id, date_notified, item_id, secondary_item_id, component_name, component_action
sort_orderstringOrder sort attribute ascending or descending.
Default: ASC
One of: ASC, DESC
component_namestringLimit result set to notifications associated with a specific component.
Default: []
component_actionstringLimit result set to notifications associated with a specific component’s action name.
Default: []
user_idintegerLimit result set to notifications addressed to a specific user.
Default: the logged in user ID.
item_idintegerLimit result set to notifications associated with a specific item ID.
Default: 0
secondary_item_idintegerLimit result set to notifications associated with a specific secondary item ID.
Default: 0
is_newbooleanLimit result set to new notifications or already read notifications.
Default: true

Top ↑

Definition Definition

GET /buddypress/v1/notifications

Top ↑

Example of use Example of use

Alert: To use the bp.apiRequest function, you need to enqueue the bp-api-request JavaScript or use it as a dependency of your script. Refer to this page to know more about loading JavaScript files in WordPress.

bp.apiRequest( {
  path: 'buddypress/v1/notifications',
  type: 'GET',
  data: {
    context: 'view',
    user_id: 23
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Create a new Screen Notification Create a new Screen Notification

Top ↑

Arguments Arguments

NameTypeDescription
user_idintegerThe ID of the user the notification is addressed to.
Default: the logged in user ID
item_idintegerThe ID of the item associated with the notification.
secondary_item_idintegerThe ID of the secondary item associated with the notification.
componentstringThe name of the BuddyPress component the notification relates to.
actionstringThe name of the component’s action the notification is about.
datestringThe date the notification was created, in the site’s timezone.
is_newintegerWhether it’s a new notification or not.
Default: 1

Top ↑

Definition Definition

POST /buddypress/v1/notifications

Top ↑

Example of use Example of use

Alert: To use the bp.apiRequest function, you need to enqueue the bp-api-request JavaScript or use it as a dependency of your script. Refer to this page to know more about loading JavaScript files in WordPress.

The sample code below shows how we could create a new notification for an activity mention.

bp.apiRequest( {
  path: 'buddypress/v1/notifications',
  type: 'POST',
  data: {
    context: 'edit',
    user_id: 2,           // The mentioned user
    item_id: 1,           // The activity ID
    secondary_item_id: 1, // The user ID of the activity author
    component: 'activity',
    action: 'new_at_mention',
    is_new: 1
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Retrieve a specific Screen Notification Retrieve a specific Screen Notification

Top ↑

Arguments Arguments

NameTypeDescription
idintegerThe unique numeric ID for the notification.
Required
contextstringScope under which the request is made; determines fields present in response.
Default: view
One of: view, edit

Top ↑

Definition Definition

GET buddypress/v1/notifications/<id>

Top ↑

Example of use Example of use

Alert: To use the bp.apiRequest function, you need to enqueue the bp-api-request JavaScript or use it as a dependency of your script. Refer to this page to know more about loading JavaScript files in WordPress.

bp.apiRequest( {
  path: 'buddypress/v1/notifications/14',
  type: 'GET',
  data: {
    context: 'view'
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Update Screen Notification whether it’s new or not Update Screen Notification whether it’s new or not

Top ↑

Arguments Arguments

NameTypeDescription
idintegerThe unique numeric ID for the notification.
Required
is_newintegerWhether it’s a new notification or not.
Default: 0

Top ↑

Definition Definition

PUT buddypress/v1/notifications/<id>

Top ↑

Example of use Example of use

Alert: To use the bp.apiRequest function, you need to enqueue the bp-api-request JavaScript or use it as a dependency of your script. Refer to this page to know more about loading JavaScript files in WordPress.

bp.apiRequest( {
  path: 'buddypress/v1/notifications/14',
  type: 'PUT',
  data: {
    context: 'edit'
    is_new: 0
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Delete a specific Screen Notification Delete a specific Screen Notification

Top ↑

Arguments Arguments

NameTypeDescription
idintegerThe unique numeric ID for the notification.
Required

Top ↑

Definition Definition

DELETE buddypress/v1/notifications/<id>

Top ↑

Example of use Example of use

Alert: To use the bp.apiRequest function, you need to enqueue the bp-api-request JavaScript or use it as a dependency of your script. Refer to this page to know more about loading JavaScript files in WordPress.

bp.apiRequest( {
  path: 'buddypress/v1/notifications/14',
  type: 'DELETE',
  data: {
    context: 'edit'
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );