Skip to main content

WordPress Chat REST API: Developer Reference for Better Messages

· 6 min read
Andrij Tkachenko
Creator of Better Messages

WordPress sites that want to do anything custom on top of their messenger — a third-party mobile app, a Slack-style bridge, a webhook integration, a custom moderation flow, a chat-to-email gateway — need a clean API. Better Messages exposes a full REST API at /wp-json/better-messages/v1/. Every operation the React front-end performs is a documented REST call, with WordPress nonce auth for logged-in users and per-request token auth for guests.

Why a REST API matters​

The plugin's React front-end is a thin client of the REST API. Anything you can do via the messenger UI you can do via the API:

  • Create a new conversation
  • Send a message (text, attachments, GIFs, stickers)
  • Add or remove participants
  • Mark threads as read / unread / muted
  • Search messages
  • Manage chat rooms and AI bots
  • Initiate voice / video calls
  • Handle guest registration and authentication

This makes Better Messages a headless messaging backend for any front-end you want to build — native iOS / Android apps, custom Vue / React layouts, Slack-style bridges, n8n / Zapier-style automation. The Capacitor mobile app shipped with Better Messages is itself a REST client against this same API.

Base URL and authentication​

Base URL: /wp-json/better-messages/v1/

Auth modes:

  • Logged-in WordPress users — standard WordPress REST auth. Send the WP REST nonce as the X-WP-Nonce header.
  • Guest users — guest registration returns an id (positive integer) and secret (30-char token). Send subsequent requests with two headers:
    • BM-Guest-ID: the positive ID
    • BM-Guest-Secret: the secret token
  • Application Passwords / Tokens — for headless front-ends, use WordPress's built-in Application Passwords or a JWT auth plugin. Better Messages respects whichever WP auth the request carries.

For a fully detailed reference of every endpoint with request / response shapes, see the dedicated REST API Reference in the docs.

Endpoint groups​

The API is grouped logically:

GroupPurpose
/threadsCreate, read, update, delete conversations. Pagination, filtering by type.
/messagesSend, edit, delete, react to messages. Attachment uploads.
/participantsAdd / remove participants from group threads and chat rooms.
/chat-roomsManage chat-room CPT entries, participants, settings.
/usersUser search for recipient selection. Profile / status.
/guests/registerGuest registration. Returns an authenticated session.
/guests/updateGuest profile updates (display name, etc.).
/ai-botsList AI bots, get bot details, manage admin-only bot config.
/callsInitiate / accept / decline / end voice & video calls.
/filesFile upload via standard POST or TUS (resumable).
/settingsPer-user settings (notification preferences, who-can-message-me, etc.).

Negative user IDs for guests​

A non-obvious but critical detail: guests are represented as negative integers in user-id contexts. A guest with bm_guests.id = 42 appears as user ID -42 in API responses (thread.participants[].user_id, message.user_id, etc.). Real WordPress users have positive IDs. Unauthenticated visitors are 0.

If you build a client against this API, treat < 0 as "guest" and > 0 as "WordPress user" in your data layer. Calling WordPress's get_userdata() on a negative ID returns NULL — use the plugin's wrapper helpers in PHP, or just key off the sign in JavaScript.

OpenAPI spec and language tabs​

The full REST API is documented in OpenAPI 3 format. The docs site at /rest-api/ renders the spec with language tabs for every endpoint — HTTP / curl / PHP / JavaScript fetch / Python requests. Copy-paste the snippet for your stack.

The OpenAPI YAML is at openapi/better-messages-api.yaml in the docs repo and can be imported into Postman / Insomnia / Bruno for ad-hoc testing.

Hooks for server-side customization​

For server-side customization (vs API-client customization), Better Messages exposes a wide hook API:

  • PHP actions / filters — modify message data before save, react to participant join / leave, override permission checks
  • JavaScript hooks — @wordpress/hooks filters on the React side for UI customization

See the Hooks & Functions Reference for the catalogue.

Common build patterns​

Headless mobile app​

Use the REST API as the backend; build a native iOS / Android app (Swift / Kotlin / React Native / Flutter / Capacitor) that talks to your WordPress site. The Better Messages-shipped mobile app is one example; you can build a fully custom one with white-label branding using the same API.

Slack / Discord bridge​

A small Node.js bot listens to Slack / Discord webhooks, then posts to Better Messages via REST when a message comes in. Use the WordPress Application Password for the bot's user account.

Zapier / n8n / Make automation​

The REST API works with any HTTP automation tool. Trigger workflows from "new message in thread X" or post messages from external systems.

AI extensions beyond the built-in bots​

Build a custom AI processor that subscribes to message-created events (via webhook or polling) and posts AI-generated replies as a bot user. The built-in AI Chat Bots cover most cases; the REST API is for the niche.

How to start​

  1. Install Better Messages from WordPress.org and activate it.
  2. Read the REST API Reference for endpoint details.
  3. (Optional) Read the Hooks & Functions Reference for server-side extension points.
  4. (Optional) Read the llms.txt and llms-full.txt for AI-assistant-friendly versions of the API docs.

Frequently asked questions​

Is the REST API stable?​

Yes — the /better-messages/v1/ namespace is the stable v1 contract. Breaking changes would land under /v2/ with the v1 endpoints kept working.

Do I need the WebSocket version to use the API?​

No — every REST endpoint works on the free version. The WebSocket version adds real-time event delivery alongside the REST API — events you would otherwise poll for arrive as WebSocket pushes.

Is there a WebSocket event API for real-time consumers?​

Yes — the WebSocket version exposes a socket.io connection that emits events for message-created, message-edited, thread-updated, participant-joined, etc. The same React front-end uses this; you can subscribe to it from your own client.

Can I disable specific endpoints for security?​

Yes — every endpoint passes through standard WordPress REST API filters (rest_request_before_callbacks, etc.). Block individual routes with a small mu-plugin if needed.

Does the API have rate limiting?​

The plugin's role-based rate limits (see Role-based access for WordPress chat) apply to API requests the same way they apply to UI actions. No separate rate-limiting layer beyond that — combine with a WAF / Cloudflare for raw HTTP rate limiting.

How do guest API consumers authenticate?​

Guest registration via POST /guests/register returns an id and secret. Subsequent requests send BM-Guest-ID and BM-Guest-Secret headers. The secret is a 30-character random string; store it securely on the client.

See also​

Install Better Messages from WordPress.org →