BuddyPress/buddypress
1
0
Fork 0
mirror of https://github.com/buddypress/buddypress.git synced 2026-07-23 21:06:56 +08:00
Code Packages Activity Actions
buddypress/docs/developer/execution-contexts/rest-api/messages.md
Mathieu Viet ef42f54ee5 Document the Messages component v2 REST API routes 
Props espellcaste

See #9145
Closes https://github.com/buddypress/buddypress/pull/388



git-svn-id: https://buddypress.svn.wordpress.org/trunk@14058 cdf35c40-ae34-48e0-9cc9-0c9da1808c22
2024-10-24 18:29:17 +00:00

12 KiB
Raw Permalink Blame History

Private Messaging REST API routes

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.

Important

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 object.

Property Description
id A unique numeric ID for the Thread.
JSON data type: integer.
Read only.
Context: view, edit.
message_id The ID of the latest message of the Thread.
JSON data type: integer.
Read only.
Context: view, edit.
last_sender_id The ID of latest sender of the Thread.
JSON data type: integer.
Read only.
Context: view, edit.
subject Title of the latest message of the Thread.
JSON data type: object (properties: raw, rendered ).
Context: view, edit.
excerpt Summary of the latest message of the Thread.
JSON data type: object (properties: raw, rendered ).
Read only.
Context: view, edit.
message Content of the latest message of the Thread.
JSON data type: object (properties: raw, rendered ).
Required.
Context: view, edit.
date Date of the latest message of the Thread, in the site's timezone.
JSON data type: string | null, format: date-time.
Read only.
Context: view, edit.
date_gmt Date of the latest message of the Thread, as GMT.
JSON data type: string | null, format: date-time.
Read only.
Context: view, edit.
unread_count Total count of unread messages into the Thread for the requested user.
JSON data type: integer.
Read only.
Context: view, edit.
sender_ids The list of user IDs for all messages in the Thread.
JSON data type: array.
Read only.
Context: view, edit.
recipients The list of Avatar1 URL objects (full, thumb) for the recipient involved into the Thread.
JSON data type: array.
Context: view, edit.
messages List of message objects for the thread.
JSON data type: array.
Read only.
Context: view, edit.
starred_message_ids List of starred message IDs.
JSON data type: array.
Read only.
Context: view, edit.

List Activities

Only logged in users will be able to fetch the threads they are involved in. Administrators can also fetch another user's threads.

Arguments

Name Description
context Scope under which the request is made; determines fields present in response.
JSON data type: string.
Default: view.
One of: view, edit.
page Current page of the threads collection.
JSON data type: integer.
Default: 1.
per_page Maximum number of threads to be returned in result set.
JSON data type: integer.
Default: 10.
Min.: 1, Max.: 100.
messages_page Current page of the messages collection.
JSON data type: integer.
Default: 1.
Min.: 1.
messages_per_page Maximum number of messages to be returned in result set.
JSON data type: integer.
Default: 10.
Min.: 1, Max.: 100.
recipients_page Current page of the recipients collection.
JSON data type: integer.
Default: 1.
Min.: 1.
recipients_per_page Maximum number of recipients to be returned in result set.
JSON data type: integer.
Default: 10.
Min.: 1, Max.: 100.
search Limit results to those matching a string.
JSON data type: string.
type Filter the result by thread status.
JSON data type: string.
One of: read, unread, all.
Default: all.
user_id Limit result set to activity items created by a specific user (ID).
JSON data type: integer.
Default: 0.
box Filter the result by box.
JSON data type: string.
One of: sentbox, inbox, starred.
Default: inbox.

Definition

GET /buddypress/v2/messages

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/messages?context=view&box=sentbox', {
	method: 'GET',
	headers: requestHeaders,
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.table( data );
} );

JSON Response

  • An array of objects representing the matching thread items on success.
  • An object containg the error code, data and message on failure.

Start a new Messages Thread or reply to an existing one

Only logged in users will be able to init a new thread or reply to an existing one.

Arguments

Name Description
id A unique numeric ID for the Thread. Required when replying to an existing Thread.
JSON data type: integer.
Default: 0.
message Content of the Message to add to the Thread.
JSON data type: string.
Required.
recipients The list of the recipients user IDs of the Message.
JSON data type: array.
Required.
sender_id The user ID of the Message sender.
JSON data type: integer.
Default: the ID of the logged in member.
subject Subject of the Message initializing the Thread.
JSON data type: string.
Default: false.

Definition

POST /buddypress/v2/messages

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/messages', {
	method: 'POST',
	headers: requestHeaders,
	body: JSON.stringify(
		{
			message: 'bapuu is the BuddyPress wapuu',
			recipients: [ 2, 3 ],
		}
	),
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object representing the created thread item or the thread reply on success.
  • An object containg the error code, data and message on failure.

Retrieve a specific Messages Thread

Only logged in users will be able to fetch a thread they are involved in. Administrators can also fetch another user's thread.

Arguments

Name Description
id A unique numeric ID for the Thread. Required.
JSON data type: integer.
messages_page Current page of the messages collection.
JSON data type: integer.
Default: 1.
Min.: 1.
messages_per_page Maximum number of messages to be returned in result set.
JSON data type: integer.
Default: 10.
Min.: 1, Max.: 100.
recipients_page Current page of the recipients collection.
JSON data type: integer.
Default: 1.
Min.: 1.
recipients_per_page Maximum number of recipients to be returned in result set.
JSON data type: integer.
Default: 10.
Min.: 1, Max.: 100.
user_id The user ID to get the thread for.
JSON data type: integer.
order Order sort attribute ascending or descending.
JSON data type: string.
One of: asc, desc.
Default: asc.

Definition

GET /buddypress/v2/messages/<id>

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/messages/2', {
	method: 'GET',
	headers: requestHeaders,
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object representing the requested thread.
  • An object containg the error code, data and message on failure.

Update metadata about a specific message of the Thread

Arguments

Name Description
id A unique numeric ID for the Thread. Required.
JSON data type: integer.
message_id By default the latest message of the thread will be updated. Specify this message ID to edit another message of the thread.
JSON data type: integer.
read Whether to mark the thread as read.
JSON data type: boolean.
Default: false
unread Whether to mark the thread as unread.
JSON data type: boolean.
Default: false
user_id The user ID to get the thread for.
JSON data type: integer.

Definition

PUT /buddypress/v2/messages/<id>

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/messages/2', {
	method: 'PUT',
	headers: requestHeaders,
	body: JSON.stringify(
		{
			user_id: 2,
			read: true,
		}
	),
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object representing the updated thread on success.
  • An object containg the error code, data and message on failure.

Delete a specific Messages Thread for a user

Note

When users request to delete a Messages Thread, they are removed from the list of recipients. As soon as the recipients list is empty, the Messages Thread is fully deleted from the database.

Arguments

Name Description
id A unique numeric ID for the activity item. Required.
JSON data type: integer.
user_id The user ID to get the thread for.
JSON data type: integer.

Definition

DELETE /buddypress/v2/messages/<id>

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/messages/2', {
	method: 'DELETE',
	headers: requestHeaders,
	body: JSON.stringify(
		{
			user_id: 2,
		}
	),
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object informing about the deleted status and the previous thread item on success.
  • An object containg the error code, data and message on failure.

Star or unstar a specific message of a Thread

Logged in users can star/unstar a specific message of a Thread`.

Arguments

Name Description
id The ID of the a specific message of the Thread. Required.
JSON data type: integer.

Important

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

Definition

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

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/messages/starred/2', {
	method: 'POST',
	headers: requestHeaders,
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object representing the thread item on success.
  • An object containg the error code, data and message on failure.

  1. This property is only available if the WordPress discussion settings allow avatars. ↩︎