Private Messaging

The Private Messaging component allow your users to talk to each other directly and in private. It’s not just limited to one-on-one discussions, private conversations can involve any number of members.

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

Schema

The schema defines all the fields that exist for a Thread of messages object.

id

integer
A unique numeric ID for the Thread.
Read only
Context: viewedit
message_id

integer
The ID of the latest message of the Thread.
Read only
Context: viewedit
last_sender_id

integer
The ID of latest sender of the Thread.
Read only
Context: viewedit
subject

object
The raw and rendered title of the latest message of the Thread.
Context: viewedit
excerpt

object
The raw and rendered summaries of the latest message of the Thread.
Read only
Context: viewedit
message

object
The raw and rendered contents of the latest message of the Thread.
Required
Context: viewedit
date

string or null
The date of the latest message of the Thread, in the site’s timezone.
Read only
Context: viewedit
date_gmt

string or null
The date of the latest message of the Thread, as GMT.
Read only
Context: viewedit
unread_count

integer
Total count of unread messages within the Thread for the requested user.
Read only
Context: viewedit
sender_ids

array
The list of user IDs for all messages within the Thread.
Read only
Context: viewedit
recipients

array
The list of recipient User Objects involved within the Thread.
Context: viewedit
messages

array
List of message objects for the Thread. 
Read only 
Context: viewedit
starred_message_ids

array
List of message IDs the logged in user added to the starred messages list (if the Star feature is active for the Pivate messaging component).
Read only 
Context: viewedit

Top ↑

List Messages Threads

Top ↑

Arguments

NameTypeDescription
contextstringScope under which the request is made; determines fields present in response.
Default: view
One of : view, edit
recipients_pageintegerCurrent page of the Recipients collection.
Minimum: 1
Default: 1
recipients_per_pageintegerMaximum number of Recipients to be returned in result set.
Minimum: 1
Default: 10
Maximum: 100
messages_pageintegerCurrent page of the Messages collection.
Minimum: 1
Default: 1
messages_per_pageintegerMaximum number of Messages to be returned in result set.
Minimum: 1
Default: 10
Maximum: 100
searchstringLimit results to the message having their subject or content matching a string.
boxstringFilter the result by box.
Default: inbox
One of : sentbox, inbox, starred
typestringFilter the result by Thread status.
Default: all
One of : all, read, unread
user_idintegerLimit result to messages created by a specific user.
Required
Default: the logged in user ID

Top ↑

Definition

GET /buddypress/v1/messages

Top ↑

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/messages',
  type: 'GET',
  data: {
    context: 'view',
    box: 'sentbox'
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Start a new Messages Thread or reply to an existing one

Top ↑

Arguments

NameTypeDescription
idintegerID of the Messages Thread.
Required when replying to an existing Thread.
subjectstringSubject of the Message initializing the Thread.
Default: No Subject
messagestringContent of the Message to add to the Thread.
Required
recipientsarrayThe list of the recipients user IDs of the Message.
Required when starting a new Thread.
sender_idintegerThe user ID of the Message sender.

Top ↑

Definition

POST /buddypress/v1/messages

Top ↑

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.

Top ↑

Starting a new Messages Thread

bp.apiRequest( {
  path: 'buddypress/v1/messages',
  type: 'POST',
  data: {
    context: 'edit',
    subject: 'Hello BuddyPress',
    message: 'BuddyPress helps you build awesome communities in WordPress.',
    /**
     * The list of user IDs for the recipients are required
     * when starting a new Thread.
     */
    recipients: [2, 3],
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Replying to an existing Messages Thread

bp.apiRequest( {
  path: 'buddypress/v1/messages',
  type: 'POST',
  data: {
    context: 'edit',
    id: 3, // The Thread ID is Required when replying.
    message: 'This is awesome.'
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Retrieve a specific Messages Thread

Top ↑

Arguments

NameTypeDescription
idintegerID of the Messages Thread.
Required

Top ↑

Definition

GET /buddypress/v1/messages/<id>

Top ↑

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/messages/5',
  type: 'GET',
  data: {
    context: 'view'
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Update metadata about a specific message of the Thread

Note: See the advanced usage chapter for more information about the way to register custom REST Fields and link them with the Message’s metadata.

Top ↑

Arguments

NameTypeDescription
idintegerID of the Messages Thread.
Required
message_idintegerBy default the latest message of the Thread will be updated. Specify this message ID to edit another message of the Thread.
readbooleanWhether to mark the thread as read.
unreadbooleanWhether to mark the thread as unread.

Top ↑

Description

PUT /buddypress/v1/messages/<id>

Top ↑

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/messages/5',
  type: 'PUT',
  data: {
    context: 'edit',
    custom_rest_field_name: 'custom rest field value'
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Delete a specific Messages Thread for a user

When a user requests to delete a Messages Thread, she/he is removed from the list of recipients. As soon as the recipients list is empty, the Messages Thread is fully deleted from the database.

Warning: If the user is not one of the recipients of the Messages Thread, the REST response will be an error object.

Top ↑

Arguments

NameTypeDescription
idintegerID of the Messages Thread.
Required
user_idintegerThe user ID to remove from the Thread.
Default: the logged in user ID
Required

Top ↑

Definition

DELETE /buddypress/v1/messages/<id>

Top ↑

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/messages/25',
  type: 'DELETE',
  data: {
    context: 'edit',
    user_id: 18
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );

Top ↑

Star or unstar a specific message of a Messages Thread

Top ↑

Arguments

NameTypeDescription
idintegerID of one of the messages of the Thread.
Required

Warning: The ID here is not a Messages Thread ID. It’s the ID of a specific message of the Messages Thread.

Top ↑

Defintion

PUT /buddypress/v1/messages/starred/<id>

Top ↑

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/messages/starred/103',
  type: 'PUT',
  data: {
    context: 'edit'
  }
} ).done( function( data ) {
  return data;
} ).fail( function( error ) {
  return error;
} );