REST API reference

This reference is for developers who want to talk to the assistant from their own code or react to chat events inside WordPress.

The plugin registers its routes in the WordPress REST API under the namespace ecomai/v1, so the base URL is https://yourstore.com/wp-json/ecomai/v1/. There are three routes. Everything else in the admin runs on internal WordPress AJAX actions that are not a public API and can change without notice.

Rate limits

Messages are limited per session_id: 20 messages per minute by default. You change this with Rate Limit (messages/minute) under Settings → Behavior → Limits & Language (1 to 100). Over the limit, the API answers with status 429:

HTTP/1.1 429 Too Many Requests

{ "error": "Rate limit exceeded. Please slow down." }

The limit is not applied while a human agent is handling the conversation. The Free plan’s conversation allowance also applies to conversations started through the API.

Endpoints

POST /ecomai/v1/message

Sends a customer message and returns the assistant’s reply. The message goes through the assistant’s normal processing: your knowledge base, product information, escalation rules and the conversation history for that session_id all apply. Flow Builder flows are driven by the chat widget and are not started by this route.

The route does not require authentication, because anonymous store visitors use the chat. Protect it the way you protect any public form, for example with your firewall’s rate limiting.

Parameters

  • message (string, required): the customer’s text.
  • session_id (string, optional): identifies the conversation. Send the same value to continue it. If you leave it out, a new one is generated and returned.
  • context (object, optional): information about where the customer is, such as page_url.
curl -X POST https://yourstore.com/wp-json/ecomai/v1/message \
  -H "Content-Type: application/json" \
  -d '{"session_id":"abc-123","message":"What is your return policy?"}'

Request body

{
  "message": "What is your return policy?",
  "session_id": "abc-123",
  "context": {
    "page_url": "https://yourstore.com/shop/"
  }
}

Response (200)

{
  "reply": "You can return any item within 30 days of delivery…",
  "session_id": "abc-123",
  "chips": ["Start a return", "Track my order"],
  "escalated": false
}
  • reply: the assistant’s answer.
  • chips: suggested quick replies, possibly empty.
  • escalated: true when the conversation has been escalated to a human.

POST /ecomai/v1/satisfaction

Saves a star rating for a conversation. No authentication.

  • session_id (string, required)
  • rating (integer, required): 1 to 5.
{
  "session_id": "abc-123",
  "rating": 5
}

Response (200)

{
  "success": true,
  "message": "Thank you for your feedback!",
  "rating": 5
}

A missing session or a rating outside 1 to 5 returns status 400 with an error message.

GET /ecomai/v1/stream

An experimental Server-Sent Events route that streams the AI’s answer as it is generated. Parameters go in the query string:

  • message (string, required)
  • session_id (string, optional)
  • nonce (string, required): the short-lived chat nonce that the plugin gives to the widget on each page load. Without a valid nonce the route answers 403.

The response has the content type text/event-stream. Each chunk is a JSON object, and the stream ends with [DONE]:

data: {"chunk":"You can return"}

data: {"chunk":" any item within 30 days"}

data: [DONE]

If the provider fails, the stream sends an error event with a message. Because the nonce is tied to a page view, this route is meant for front-end code running on your store, not for server-to-server calls. For those, use POST /message.

PHP action hooks

If your code runs on the same WordPress site, hooks are simpler than HTTP calls. The plugin fires these actions:

  • ecomai_conversation_started ($session_id, $context): a new conversation was saved.
  • ecomai_conversation_escalated ($session_id, $contact): a customer submitted the escalation form.
  • ecomai_lead_captured ($lead): an e-mail address was captured.
  • ecomai_chat_purchase ($order_id, $order_data): an order was placed after a chat.
  • ecomai_satisfaction_rated ($session_id, $rating): a customer rated the conversation.
  • ecomai_discount_offered ($session_id, $discount): the assistant offered a coupon.
add_action( 'ecomai_lead_captured', function ( $lead ) {
    // $lead['email'], $lead['name'], $lead['session_id'], $lead['source']
    my_crm_add_contact( $lead['email'], $lead['name'] );
} );

One filter controls the automatic widget: ecomai_should_inject_global_widget. Return false from it to stop the widget being added to the current page.

Shortcode

Use [ecomai_chatbot] to place the chat yourself instead of (or in addition to) the automatic widget:

  • [ecomai_chatbot]: the floating widget.
  • [ecomai_chatbot mode="inline"]: a chat embedded in the page content.
  • [ecomai_chatbot type="support"]: the dedicated Support Bot for a help page Pro.

Webhooks

To receive the same events on another server, use Webhooks Pro. That guide documents the payload and the signature check.

Still stuck?

Check the troubleshooting guide, or contact support and tell us what you tried.