Skip to content

API reference

These are the endpoints behind the widget. They live under your Mikabot app domain, accept JSON, and return JSON. Use them when you build your own chat surface or track products you render yourself.

How a request is accepted

Every chat request is checked against the chatbot’s configuration before it is answered. A request is rejected without an answer when:

  • store_id_not_found — no store_id was sent, or it matches no chatbot
  • domain_not_found — no page_url was sent, or it has no hostname
  • store_id_domain_mismatch — the hostname in page_url is not the chatbot’s Domain. The match is exact, on hostname and port only, so www.yourshop.com and yourshop.com are different values.
  • store_not_active — the chatbot is switched off

Rejected requests do not appear in Chat conversations. If your requests are being dropped and the four causes above do not explain it, contact support with your chatbot key and the page_url you are sending.

Send a message

POST /api/chat/send

{
  "message": "Which watering can suits a small balcony?",
  "store_id": "st_your_chatbot_key",
  "page_url": "https://yourshop.com/collections/tools",
  "session_id": "visitor-session-id",
  "conversation_history": [],
  "detected_language": "en"
}
  • message (required) — the visitor’s text, maximum 150 characters
  • store_id (required) — your chatbot key
  • page_url (required) — the page the visitor is on. It drives the domain check above and is shown in your chat logs, so a request without it is rejected.
  • session_id — groups turns into one conversation. Generate one per visitor, up to 100 characters.
  • conversation_history — earlier turns. Send an empty array for a one-off question.
  • detected_language — overrides automatic detection

The answer is returned in the response field, together with any products the bot decided to show.

Store information

POST /api/ai-responses/store-info returns the public details used in greetings and placeholders. Send store_id, language, and page_url.

Product tracking

Use these when you render product cards yourself and still want the numbers in your dashboard.

POST /api/product/click

  • product_external_id (required) — the product’s ID in your feed
  • click_type (required) — buy_now, view_product, or ask_ai
  • session_id, page_url, detected_language (optional)

POST /api/product/impressions

  • products (required) — an array, each entry with a product_external_id
  • impression_type (required) — display, search_result, or direct_hit
  • session_id, page_url, detected_language (optional)

GET /api/product/click-stats

  • period (optional) — today, week, month, or all. Defaults to all.
  • product_id (optional) — limit the totals to one product

GET /api/product/{productId}/click-stats returns the same totals for a single product.

Errors

  • 402 with code message_limit_reached — the monthly message limit of the billing account is used up. Chat stops until the next period. Note that the widget itself stops loading in this state, so you will only see this code if you call the endpoint directly.
  • 503 with code api_unavailable — Mikabot is temporarily unavailable.
  • 422 — a field failed validation, most often a message over 150 characters.
  • Other failures return an error field with a readable message.

Requests that error are not counted against your monthly message limit.