Contents
On this page
Plugixa Chat REST API - Plugixa Chat
The integration surface for Plugixa Chat: widgets with their channels and targeting rules, the leads the contact form collects, click analytics, and in Pro the agents, webhooks, CRM connections and A/B tests. Enough to build widgets from a script, pull leads into another system, or feed the figures to a BI tool.
Everything the admin app does, it does over REST, under the namespace plugixa-chat/v1. Every permission the screens enforce is checked at the endpoint rather than in the page.
This is the API the plugin’s own screens and widget use. It is not separately versioned, and routes, parameters or response shapes may change between versions. Pin the plugin version you build against, and test after updating.
Base URL
https://your-site.example/wp-json/plugixa-chat/v1
On a site with plain permalinks, pass the route as a parameter instead:
https://your-site.example/?rest_route=/plugixa-chat/v1/widgets
Authentication
The plugin adds no API keys of its own. It relies on whatever WordPress accepts for REST requests, then checks the capabilities of the user WordPress identified. From a script, use an Application Password for an account that holds the capabilities below, over HTTPS:
curl -s "https://your-site.example/wp-json/plugixa-chat/v1/widgets" \
-u "admin:$WP_APP_PASSWORD"
| Caller | How it signs in |
|---|---|
| A script or another system | An Application Password, or any other method WordPress accepts |
| The admin app | The logged-in cookie plus a nonce in X-WP-Nonce, the normal WordPress way |
| The widget on your site | Nothing: it uses the public routes with a page token |
Capabilities
Each route needs one of the plugin’s capabilities.
| Capability | Allows |
|---|---|
plugixa_chat_view |
List and read widgets, channels, leads, analytics and the Pro records |
plugixa_chat_create |
Create and duplicate widgets, and create Pro records |
plugixa_chat_edit |
Update records, mark leads read, and the Pro actions (test a webhook, check a CRM connection, start and end an A/B test) |
plugixa_chat_delete |
Move records to the trash, restore them and purge them |
plugixa_chat_export |
Download leads as CSV |
plugixa_chat_manage_settings |
The settings screen, which is not part of this reference |
Two more exist. plugixa_chat_manage opens the admin app and is never granted directly: holding any capability above gives it. plugixa_chat_reply is defined, but no route in 1.0.0 checks it.
Administrators hold them all from activation, and an account that can manage options is always treated as holding them. No other role is given any. They are ordinary WordPress capabilities, so a role editor can grant them to a role or to one person. The verdict can be changed in PHP with the plugixa_chat_user_can filter: see Hooks.
Privacy. A lead carries a name, an e-mail address and a phone number. Anyone who holds
plugixa_chat_viewcan read them.
Responses
Every successful response is wrapped the same way:
{
"success": true,
"data": { "id": 2, "name": "Main widget" },
"meta": { "total": 12, "pages": 1 }
}
meta is only present when it has something in it. Ids are integers and booleans are real booleans, but some columns come back as strings, notably created_by and modified_by. Datetimes are UTC strings in the form 2026-11-12 09:30:00, unless a page says otherwise.
Lists and pagination
Paged list endpoints accept the same parameters, and put the totals in meta, not in headers.
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
integer |
1 |
Page to return, from 1 |
per_page |
integer |
50 |
Rows per page, 1 to 200 |
search |
string |
Substring search over the columns each endpoint lists | |
orderby |
string |
id |
One of the sortable columns each endpoint lists. Anything else falls back to id |
order |
string |
desc |
asc or desc |
view |
string |
active |
active, or trash for trashed rows only |
The trash
Widgets, leads and the Pro records are soft-deleted. DELETE /{base}/{id} moves a record to the trash, where it stops appearing in single reads and in lists unless you ask for view=trash. POST /{base}/{id}/restore brings it back, and DELETE /{base}/{id}/purge deletes it for good.
Endpoints
| Resource | Endpoints |
|---|---|
| Widgets | List, Create, Get, Update, Delete, Restore, Purge, Duplicate |
| Channels | List |
| Leads | List, Get, Update, Delete, Restore, Purge, Unread count, Export, Answers PRO, Submit (public) |
| Analytics | Summary, Record events (public) |
| Context | Get (public) |
| Agents PRO | List, Create, Get, Update, Delete, Restore, Purge |
| Webhooks PRO | List, Create, Get, Update, Delete, Restore, Purge, Test |
| CRM connections PRO | List, Create, Get, Update, Delete, Restore, Purge, Providers, Lists, Check |
| A/B tests PRO | List, Create, Get, Update, Delete, Restore, Purge, Start, End, Results |
| Orders PRO | Look up (public, needs WooCommerce) |
A part of the plugin that is switched off does not register its routes, so they answer 404. The Pro routes exist only on a site running Plugixa Chat Pro.
Public routes
Four routes accept a visitor who is not logged in. They are what the widget calls.
| Route | Does | Limit per visitor |
|---|---|---|
GET /context |
The site’s time, the visitor’s country, whether they are logged in, and fresh page tokens | None |
POST /events |
Records analytics events | 60 every five minutes |
POST /leads/submit |
Stores a contact form message | 5 every five minutes |
POST /orders/lookup PRO |
Looks up a WooCommerce order | 10 every five minutes |
The three POST routes need a page token. It is not a WordPress nonce, because the page that carries it is often served from a cache and shared by every visitor.
- Every page that loads the widget prints the tokens in the
tokensobject of the JSON block with the idplugixa-chat-config, andGET /contextreturns fresh ones. There is one foreventsand one forlead; the order look-up uses theleadtoken. - Send it in the
X-Plugixa-Chat-Tokenheader, or astokenin the JSON body. A token in the query string is not read. - A token is valid for 12 to 24 hours.
- When the request carries an
OriginorRefererheader, its host must be the site’s own. A request with neither passes this check. - The limit counts requests from one visitor (an address, kept only as a hash) over five minutes that start at their first request.
| Status | Code | When |
|---|---|---|
403 |
plugixa_chat_missing_token |
No token was sent |
403 |
plugixa_chat_stale_token |
The token has expired, or is not one for this route. Fetch /context and try again |
403 |
plugixa_chat_bad_origin |
The request came from another site |
429 |
plugixa_chat_rate_limited |
The visitor’s limit for this route is used up |
The token says “this came from a page this site rendered recently”. It is not authentication: the limits, and the contact form’s own spam checks, are what make replaying it pointless.
Webhook events
Rather than polling for leads, you can have them pushed to you PRO. Each lead.created delivery is a signed POST: see Webhooks for the body and how to check the X-Plugixa-Signature header. Endpoints can be managed in the admin or with the webhook routes.
Errors
Errors use the standard WordPress shape:
{
"code": "plugixa_chat_forbidden",
"message": "You are not allowed to do that.",
"data": { "status": 403 }
}
A form error also carries a message per field in data.fields. These can come back from any endpoint that needs a login. Each endpoint page lists its own errors on top of them.
| Status | Code | When |
|---|---|---|
401 |
plugixa_chat_forbidden |
Not signed in: the request carried no credentials. |
401 |
incorrect_password, invalid_username |
WordPress refused the Application Password before the plugin saw the request. |
403 |
plugixa_chat_forbidden |
Signed in, but the user lacks the capability the route needs. |
403 |
rest_cookie_invalid_nonce |
A cookie request with a missing or stale X-WP-Nonce. |
404 |
plugixa_chat_not_found |
The record does not exist, or is in the trash. |
404 |
rest_no_route |
No such route or method, the part of the plugin that registers it is switched off, or the route is Pro and the site runs the free edition. |
400 |
rest_invalid_param |
A parameter failed validation, for example per_page above 200 or order other than asc/desc. |
There is no rate limit on routes that need a login.
Filtering what comes back
| Hook | Changes |
|---|---|
plugixa_chat_filter_output |
The data of every successful response, with the entity type (widget, lead, …) as second argument. The place to hide fields from some users |
plugixa_chat_user_can |
Whether a user may perform an action on an entity |
plugixa_chat_max_widgets |
A ceiling on the number of widgets. 0, the default, means none |
plugixa_chat_register_rest_routes |
Fires when the plugin’s routes are registered, with the namespace and the plugin’s container: the place to add your own routes |
See Hooks for the full set.
Troubleshooting
| Symptom | Usual cause |
|---|---|
401 from a script |
The Application Password is wrong, the request is not over HTTPS, or the host strips the Authorization header. |
403 for a user who is not an administrator |
Their role lacks the plugixa_chat_* capability the route needs. |
401 or 403 from the browser |
The nonce is missing or stale. Reload the admin. |
404 on a route that should exist |
Its part of the plugin is switched off, it is a Pro route on the free edition, or (for /orders/lookup) WooCommerce is not active. |
403 plugixa_chat_stale_token from the widget |
The page was cached for more than a day. The widget fetches /context and retries by itself. |
| A widget change does not show | A full-page cache is still serving the old page. Purge it: the plugixa_chat_config_invalidated action fires on every save. |
See also
Quick Links
Share