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_view can 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 tokens object of the JSON block with the id plugixa-chat-config, and GET /context returns fresh ones. There is one for events and one for lead; the order look-up uses the lead token.
  • Send it in the X-Plugixa-Chat-Token header, or as token in 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 Origin or Referer header, 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

  • Change behaviour in PHP instead: Hooks.
  • Receive leads in another system: Webhooks PRO.
  • What a lead holds: Leads.

Quick Links

Share