Skip to main content
Version: 1.0

Better Messages REST API

The Better Messages REST API exposes every messenger operation — creating conversations, sending messages, managing participants, moderation, friend lists, settings, voice messages, file attachments, and more — over a standard WordPress REST API namespace. It powers both the official Better Messages JavaScript client and the iOS / Android mobile apps, and you can use it directly to build integrations, bots, mobile clients, sync workers, or any external service that needs to read or write messenger data.

Base URL: https://your-site.com/wp-json/better-messages/v1

All routes are rooted at the /wp-json/better-messages/v1 namespace and follow standard WordPress REST API conventions.

Authentication: Most endpoints require an authenticated WordPress user. Three authentication methods are supported:

  • Cookie authentication — the default for browser-based requests. Send the standard WordPress nonce header (X-WP-Nonce).
  • Application passwords — for server-to-server or external integrations. Use HTTP Basic auth with the username and an application password (WordPress 5.6+).
  • Custom authentication — override the auth check via the better_messages_rest_is_user_authorized PHP filter. Useful for bridging JWT, OAuth, or custom tokens.

Guest authentication — for sites with Guest Chat enabled, unauthenticated visitors can interact with the messenger using two HTTP headers: BM-Guest-ID (positive guest database id) and BM-Guest-Secret (30-character token returned during guest registration). Guests are identified internally as negative integer user IDs so they don't collide with real WordPress users.

Authorization — endpoint access depends on user capabilities, thread participation, plugin settings, and any custom better_messages_capabilities filter logic. A request that is authenticated but not authorized for a specific thread or action returns 403 Forbidden. Endpoints marked Public in their tag description do not require authentication at all.

Response format — all endpoints return JSON. Errors follow the WordPress REST API envelope ({ code, message, data: { status } }). Successful responses return the requested resource directly without wrapping.

Rate limiting — the API itself does not impose hard rate limits, but several settings (message-send cooldown, max messages per minute, mass-messaging quota) are enforced on the relevant endpoints. Those return 429 Too Many Requests when triggered.