WordPress-Native Developer API

Better Messages is built on standard WordPress conventions — every meaningful event in the messaging workflow is exposed as a PHP action, every data point is filterable, and every server interaction has a REST endpoint. Theme authors, plugin developers, and site builders can extend or override behavior without forking the plugin.

What it adds#

REST API — full programmatic access to threads, messages, users, and settings (REST reference)
PHP actions — hook into events like message sent, conversation created, participant added (PHP actions reference)
PHP filters — modify data like message text, user permissions, displayed names (PHP filters reference)
JavaScript hooks — extend the frontend with wp.hooks-style actions and filters
Custom CSS hooks — every UI surface has stable class names for styling
Standard WordPress coding patterns — no proprietary frameworks, no compiled-only formats

Hook prefix#

Hooks were originally prefixed bp_better_messages_* (legacy from BuddyPress origins). The current prefix is better_messages_*. Both prefixes are still honored for backwards compatibility — existing customizations don't break on upgrade.

// Modern form (preferred — most new code uses this)
add_action('better_messages_message_sent', 'my_message_listener');

// Legacy form (still works — many established hooks live under this prefix)
add_filter('bp_better_messages_after_format_message', 'my_custom_renderer', 10, 4);

What you can build with the API#

Customization	Hooks involved
Restrict who can send a message	`better_messages_can_send_message` filter (return `false` to block)
Add a custom message renderer (e.g. Markdown extensions)	`bp_better_messages_after_format_message` filter
Trigger an integration on every new message	`better_messages_message_sent` action
Auto-archive old threads	WP-Cron + REST API `DELETE /threads/{id}`
Display a custom badge next to user names	`bp_better_messages_display_name` filter
Override the verified-badge source	`better_messages_is_verified` filter
Notify external system on conversation creation	`bp_better_messages_new_thread_created` action
Customize the AI-bot mention placeholder behaviour	`better_messages_ai_providers_info` filter

REST API at a glance#

The REST API lives at /wp-json/better-messages/v1/. Authenticated requests use the standard WordPress REST authentication (cookie + nonce for logged-in users, application passwords for external apps).

Key endpoints:

GET /threads — list conversations for the current user
POST /threads — create a new conversation
GET /threads/{id}/messages — fetch a thread's messages
POST /threads/{id}/messages — send a message
GET /users — search users for the recipient picker

Full reference with request/response shapes is at /rest-api/.

Frequently asked questions#

Is the REST API rate-limited?#

WordPress's REST API doesn't rate-limit by default. Better Messages adds soft limits on a few endpoints (recipient picker, search) to prevent abuse. Rate limits are filterable — see the developer reference.

How do I authenticate REST calls from a separate frontend app?#

Use WordPress's application passwords feature. Each user can generate a per-app password and you authenticate via Basic Auth on the REST endpoint.

Can I create messages on behalf of a user without their session?#

Yes — server-side PHP code (running as the bot or as an admin) can call Better_Messages()->functions->new_message() directly, bypassing REST authentication.

Do hooks fire for AI bot messages?#

Yes. AI bot messages flow through the same hook pipeline as user messages — your custom action handlers will be invoked.

Where can I see the full hooks reference?#

See the Hooks & functions reference in the sidebar, organized by PHP actions, PHP filters, PHP functions, JS actions, JS filters, and JS functions.