WordPress Chat REST API: Developer Reference for Better Messages

August 18, 2020 · 6 min read

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:

Group	Purpose
`/threads`	Create, read, update, delete conversations. Pagination, filtering by type.
`/messages`	Send, edit, delete, react to messages. Attachment uploads.
`/participants`	Add / remove participants from group threads and chat rooms.
`/chat-rooms`	Manage chat-room CPT entries, participants, settings.
`/users`	User search for recipient selection. Profile / status.
`/guests/register`	Guest registration. Returns an authenticated session.
`/guests/update`	Guest profile updates (display name, etc.).
`/ai-bots`	List AI bots, get bot details, manage admin-only bot config.
`/calls`	Initiate / accept / decline / end voice & video calls.
`/files`	File upload via standard POST or TUS (resumable).
`/settings`	Per-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#

Install Better Messages from WordPress.org and activate it.
Read the REST API Reference for endpoint details.
(Optional) Read the Hooks & Functions Reference for server-side extension points.
(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.