Naar de inhoud

API-referentie

Dit zijn de endpoints achter de widget. Ze staan onder je Mikabot-appdomein, accepteren JSON en geven JSON terug. Gebruik ze als je een eigen chatinterface bouwt of producten volgt die je zelf rendert.

Hoe een verzoek geaccepteerd wordt

Elk chatverzoek wordt tegen de configuratie van de chatbot gecontroleerd voordat het beantwoord wordt. Een verzoek wordt zonder antwoord geweigerd wanneer:

  • store_id_not_found — er is geen store_id meegestuurd, of hij hoort bij geen enkele chatbot
  • domain_not_found — er is geen page_url meegestuurd, of die bevat geen hostnaam
  • store_id_domain_mismatch — de hostnaam in page_url is niet het veld Domain van de chatbot. De match is exact, alleen op hostnaam en poort, dus www.jouwshop.be en jouwshop.be zijn verschillende waarden.
  • store_not_active — de chatbot staat uit

Geweigerde verzoeken verschijnen niet in Chat conversations. Worden je verzoeken geweigerd en verklaren de vier oorzaken hierboven het niet, neem dan contact op met je chatbotsleutel en de page_url die je verstuurt.

Een bericht versturen

POST /api/chat/send

{
  "message": "Welke gieter past bij een klein balkon?",
  "store_id": "st_your_chatbot_key",
  "page_url": "https://jouwshop.be/collecties/gereedschap",
  "session_id": "visitor-session-id",
  "conversation_history": [],
  "detected_language": "nl"
}
  • message (verplicht) — de tekst van de bezoeker, maximaal 150 tekens
  • store_id (verplicht) — je chatbotsleutel
  • page_url (verplicht) — de pagina waarop de bezoeker zich bevindt. Hij voedt de domeincontrole hierboven en verschijnt in je chatlogs, dus een verzoek zonder deze waarde wordt geweigerd.
  • session_id — groepeert beurten tot één gesprek. Genereer er één per bezoeker, maximaal 100 tekens.
  • conversation_history — eerdere beurten. Stuur een lege array voor een losse vraag.
  • detected_language — overschrijft de automatische detectie

Het antwoord komt terug in het veld response, samen met de producten die de bot besloot te tonen.

Winkelinformatie

POST /api/ai-responses/store-info geeft de publieke gegevens terug die in begroetingen en placeholders gebruikt worden. Stuur store_id, language en page_url mee.

Producttracking

Gebruik deze endpoints als je productkaarten zelf rendert en de cijfers toch in je dashboard wilt zien.

POST /api/product/click

  • product_external_id (verplicht) — het ID van het product in je feed
  • click_type (verplicht) — buy_now, view_product of ask_ai
  • session_id, page_url, detected_language (optioneel)

POST /api/product/impressions

  • products (verplicht) — een array, elk item met een product_external_id
  • impression_type (verplicht) — display, search_result of direct_hit
  • session_id, page_url, detected_language (optioneel)

GET /api/product/click-stats

  • period (optioneel) — today, week, month of all. Standaard all.
  • product_id (optioneel) — beperkt de totalen tot één product

GET /api/product/{productId}/click-stats geeft dezelfde totalen voor één product.

Fouten

  • 402 met code message_limit_reached — de maandelijkse berichtenlimiet van het factuuraccount is op. De chat stopt tot de volgende periode. De widget zelf laadt in die toestand niet meer, dus je ziet deze code alleen als je het endpoint rechtstreeks aanroept.
  • 503 met code api_unavailable — Mikabot is tijdelijk niet beschikbaar.
  • 422 — een veld voldeed niet aan de validatie, meestal een message van meer dan 150 tekens.
  • Andere fouten geven een veld error terug met een leesbare melding.

Verzoeken die falen tellen niet mee voor je maandelijkse berichtenlimiet.

Zie ook