Aller au contenu

Référence API

Voici les endpoints derrière le widget. Ils vivent sous le domaine de votre application Mikabot, acceptent du JSON et renvoient du JSON. Utilisez-les pour construire votre propre interface de chat ou pour suivre des produits que vous affichez vous-même.

Comment une requête est acceptée

Chaque requête de chat est contrôlée face à la configuration du chatbot avant d’être traitée. Une requête est rejetée sans réponse lorsque :

  • store_id_not_found — aucun store_id n’a été envoyé, ou il ne correspond à aucun chatbot
  • domain_not_found — aucune page_url n’a été envoyée, ou elle ne contient pas de nom d’hôte
  • store_id_domain_mismatch — le nom d’hôte de page_url n’est pas le champ Domain du chatbot. La correspondance est exacte, sur le nom d’hôte et le port uniquement : www.votreboutique.com et votreboutique.com sont deux valeurs différentes.
  • store_not_active — le chatbot est désactivé

Les requêtes rejetées n’apparaissent pas dans Chat conversations. Si vos requêtes sont rejetées et que les quatre causes ci-dessus ne l’expliquent pas, contactez le support avec votre clé de chatbot et la page_url que vous envoyez.

Envoyer un message

POST /api/chat/send

{
  "message": "Quel arrosoir convient à un petit balcon ?",
  "store_id": "st_your_chatbot_key",
  "page_url": "https://votreboutique.com/collections/outils",
  "session_id": "visitor-session-id",
  "conversation_history": [],
  "detected_language": "fr"
}
  • message (obligatoire) — le texte du visiteur, 150 caractères maximum
  • store_id (obligatoire) — votre clé de chatbot
  • page_url (obligatoire) — la page où se trouve le visiteur. Elle alimente le contrôle de domaine ci-dessus et s’affiche dans vos journaux : une requête sans elle est rejetée.
  • session_id — regroupe les échanges en une conversation. Générez-en un par visiteur, 100 caractères maximum.
  • conversation_history — les échanges précédents. Envoyez un tableau vide pour une question isolée.
  • detected_language — remplace la détection automatique

La réponse est renvoyée dans le champ response, accompagnée des produits que le bot a décidé d’afficher.

Informations de la boutique

POST /api/ai-responses/store-info renvoie les informations publiques utilisées dans les salutations et les placeholders. Envoyez store_id, language et page_url.

Suivi des produits

À utiliser lorsque vous affichez vos propres fiches produit et souhaitez malgré tout les chiffres dans votre tableau de bord.

POST /api/product/click

  • product_external_id (obligatoire) — l’identifiant du produit dans votre flux
  • click_type (obligatoire) — buy_now, view_product ou ask_ai
  • session_id, page_url, detected_language (facultatifs)

POST /api/product/impressions

  • products (obligatoire) — un tableau, chaque entrée avec un product_external_id
  • impression_type (obligatoire) — display, search_result ou direct_hit
  • session_id, page_url, detected_language (facultatifs)

GET /api/product/click-stats

  • period (facultatif) — today, week, month ou all. Vaut all par défaut.
  • product_id (facultatif) — limite les totaux à un seul produit

GET /api/product/{productId}/click-stats renvoie les mêmes totaux pour un produit donné.

Erreurs

  • 402 avec le code message_limit_reached — la limite mensuelle de messages du compte de facturation est épuisée. Le chat s’arrête jusqu’à la période suivante. Le widget lui-même cesse de se charger dans cet état : vous ne verrez donc ce code qu’en appelant l’endpoint directement.
  • 503 avec le code api_unavailable — Mikabot est temporairement indisponible.
  • 422 — un champ a échoué à la validation, le plus souvent un message de plus de 150 caractères.
  • Les autres échecs renvoient un champ error avec un message lisible.

Les requêtes en erreur ne sont pas comptées dans votre limite mensuelle.

À voir aussi