API www.achatbot.eu

1. Vue d'ensemble

Deux modes d'intégration complémentaires :

2. Authentification (API client)

Deux types de clés, fournies par ACHATBOT.EU :

Les clés peuvent être révoquées à tout moment depuis le tableau de bord.

Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxx

Base URL : https://www.achatbot.eu/console/api/client · Limite : 120 requêtes/minute par clé.

GET/me — identifier votre clé

Avec une clé d'assistant, obtenez le slug et les URLs publiques. Avec une clé compte, obtenez la liste de vos assistants.

curl -H "Authorization: Bearer $API_KEY" \
  https://www.achatbot.eu/console/api/client/me

Réponse clé d'assistant :

{
  "scope": "agent",
  "agent": "votre-chatbot",
  "title": "Mon assistant",
  "public_config_url": "https://www.achatbot.eu/console/api/public/agents/votre-chatbot/config",
  "public_predict_url": "https://www.achatbot.eu/console/api/public/agents/votre-chatbot/predict",
  "chat_page_url": "https://www.achatbot.eu/console/chat.html?agent=votre-chatbot",
  "widget_snippet": "AkiChat.init({ agent: \"votre-chatbot\" })"
}

Navigateur vs serveur : la clé sert aux appels serveur-à-serveur (chat backend, sources, usage). Pour une page web, utilisez les URLs public_* ou l'iframe / widget (section 7).

2 bis. Multi-assistants (clé compte)

Pour créer un chatbot par formation, produit ou espace (isolation des corpus), demandez une clé compte ak_account_… (tableau de bord → onglet assistant Clés API → section « Clé compte API (multi-assistants) »). Les endpoints /chat et /sources sans préfixe /agents/:slug restent réservés aux clés d'assistant ak_….

Tableau des endpoints (clé compte)

GET/me — réponse clé compte

{
  "scope": "account",
  "group": "mon-organisation",
  "group_name": "Mon organisation",
  "agents_count": 2,
  "agents": [
    {
      "agent": "assistant-formation-a",
      "title": "Assistant — Formation A",
      "archived": false,
      "chat_page_url": "https://www.achatbot.eu/console/chat.html?agent=assistant-formation-a&lang=fr",
      "public_config_url": "https://www.achatbot.eu/console/api/public/agents/assistant-formation-a/config",
      "public_predict_url": "https://www.achatbot.eu/console/api/public/agents/assistant-formation-a/predict",
      "widget_snippet": "AkiChat.init({ agent: \"assistant-formation-a\", lang: \"fr\" })"
    }
  ]
}

GET/agents — lister

curl -H "Authorization: Bearer $ACCOUNT_KEY" \
  "https://www.achatbot.eu/console/api/client/agents?externalId=recFormation123&page=1&limit=50"

{
  "total": 1,
  "page": 1,
  "limit": 50,
  "agents": [
    {
      "agent": "assistant-formation-a",
      "title": "Assistant — Formation A",
      "archived": false,
      "externalId": "recFormation123",
      "language": "fr",
      "chat_page_url": "https://www.achatbot.eu/console/chat.html?agent=assistant-formation-a&lang=fr",
      "public_config_url": "…",
      "public_predict_url": "…",
      "widget_snippet": "AkiChat.init({ agent: \"assistant-formation-a\", lang: \"fr\" })"
    }
  ]
}

POST/agents — créer un chatbot

Corps multipart (PDF) ou JSON. Champs principaux :

curl -H "Authorization: Bearer $ACCOUNT_KEY" \
  -F "title=Assistant — Ma formation" \
  -F "language=fr" \
  -F "externalId=recFormation123" \
  -F 'config={"welcomeMessage":"Bonjour !","audience":"en_formation","instructions":"Réponds à partir des PDF fournis.","suggestions":["Question 1 ?","Question 2 ?"]}' \
  -F "file=@support.pdf" \
  https://www.achatbot.eu/console/api/client/agents

externalId : un second appel avec le même identifiant renvoie l'agent existant (200, champ idempotent: true) — pas de doublon. Recommandé pour toute intégration MCP ou script (retries sans créer mon-agent-1, mon-agent-2…).

Réponse 201 :

{
  "agent": "assistant-ma-formation",
  "title": "Assistant — Ma formation",
  "archived": false,
  "externalId": "recFormation123",
  "language": "fr",
  "chat_page_url": "https://www.achatbot.eu/console/chat.html?agent=assistant-ma-formation&lang=fr",
  "public_config_url": "https://www.achatbot.eu/console/api/public/agents/assistant-ma-formation/config",
  "public_predict_url": "https://www.achatbot.eu/console/api/public/agents/assistant-ma-formation/predict",
  "widget_snippet": "AkiChat.init({ agent: \"assistant-ma-formation\", lang: \"fr\" })",
  "api_key": "ak_…",
  "config": {
    "welcomeMessage": "Bonjour !",
    "disclaimer": "",
    "suggestions": ["Question 1 ?", "Question 2 ?"],
    "audience": "en_formation",
    "instructions": "Réponds à partir des PDF fournis.",
    "colors": { "primary": "#1C2A6E" }
  },
  "sources": {
    "total_chunks": 24,
    "items": [
      {
        "id": 101,
        "type": "pdf",
        "filename": "support.pdf",
        "display_title": "Support de cours",
        "chunks": 24,
        "status": "indexed",
        "size_bytes": 1048576,
        "created_at": "2026-06-18T10:00:00.000Z",
        "updated_at": "2026-06-18T10:02:00.000Z",
        "editable": false,
        "external_source_id": null
      }
    ]
  },
  "usage": { "month": "2026-06", "user_messages": 0, "sessions": null }
}

Champs config (création et PATCH)

Apparence et comportement de l'assistant — lisibles via GET /agents/:slug, modifiables via PATCH ou le MCP achatbot_agent_update. Le widget et l'iframe appliquent les mêmes réglages via la config publique (sans clé API).

GET/agents/:slug — état complet

Structure identique à la réponse POST /agents (sans api_key). Utile pour alimenter un panneau d'édition (LMS, back-office).

{
  "agent": "assistant-ma-formation",
  "title": "Assistant — Ma formation",
  "externalId": "recFormation123",
  "language": "fr",
  "chat_page_url": "…",
  "config": { "instructions": "…", "welcomeMessage": "…", "disclaimer": "…", "colors": { "primary": "#E85D04" }, "logoUrl": "https://…", "suggestions": [], "widgetTeasers": [] },
  "sources": {
    "total_chunks": 42,
    "items": [
      {
        "id": 101,
        "type": "pdf",
        "filename": "support.pdf",
        "display_title": "Support de cours",
        "chunks": 24,
        "status": "indexed",
        "editable": false
      },
      {
        "id": 103,
        "type": "web",
        "filename": "web:example.com",
        "display_title": "example.com",
        "chunks": 18,
        "status": "indexed",
        "editable": false
      }
    ]
  },
  "usage": { "month": "2026-06", "user_messages": 12, "sessions": 8 }
}

Les consignes (config.instructions) alimentent le prompt de l'assistant, pas la liste des sources. N’envoyez pas de consignes via textSources.

Contenu texte intégral : GET /agents/:slug/sources/:id (champs title, content).

PATCH/agents/:slug — modifier sans recréer

curl -X PATCH -H "Authorization: Bearer $ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Nouveau titre","language":"nl","config":{"instructions":"Nouvelle consigne…","welcomeMessage":"Welkom","colors":{"primary":"#E85D04"},"logoUrl":"https://example.com/logo.png","suggestions":["…","…"],"widgetTeasers":["Hulp nodig?"]}}' \
  https://www.achatbot.eu/console/api/client/agents/mon-agent

Les changements de config.instructions sont effectifs immédiatement sur les réponses (sans réindexer les PDF).

Sources par assistant

Même sémantique que la section 4, préfixée par /agents/:slug. Exemples :

# Lister
curl -H "Authorization: Bearer $ACCOUNT_KEY" \
  https://www.achatbot.eu/console/api/client/agents/mon-agent/sources

# Ajouter un PDF (lien ressource LMS optionnel)
curl -H "Authorization: Bearer $ACCOUNT_KEY" \
  -F "file=@nouveau-doc.pdf" \
  -F "externalSourceId=recMateriel456" \
  -F "display_title=Annexe cours" \
  https://www.achatbot.eu/console/api/client/agents/mon-agent/sources

# Modifier une source texte / consigne
curl -X PATCH -H "Authorization: Bearer $ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Nouvelle consigne pédagogique…"}' \
  https://www.achatbot.eu/console/api/client/agents/mon-agent/sources/102

# Contexte d'usage (quand / comment utiliser la source)
curl -X PATCH -H "Authorization: Bearer $ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usage_context":"Catalogue éditeur — n'\''utiliser que si l'\''utilisateur demande d'\''autres ouvrages"}' \
  https://www.achatbot.eu/console/api/client/agents/mon-agent/sources/102

# Découpage documentaire (1 segment forcé pour brève / article court)
curl -X PATCH -H "Authorization: Bearer $ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"single_chunk":true}' \
  https://www.achatbot.eu/console/api/client/agents/mon-agent/sources/102

# Supprimer
curl -X DELETE -H "Authorization: Bearer $ACCOUNT_KEY" \
  https://www.achatbot.eu/console/api/client/agents/mon-agent/sources/101

GET/agents/:slug/usage

curl -H "Authorization: Bearer $ACCOUNT_KEY" \
  "https://www.achatbot.eu/console/api/client/agents/mon-agent/usage?month=2026-06"

DELETE/agents/:slug

Supprime l'assistant, son contenu indexé, ses sources et ses clés. L'URL chat_page_url renvoie ensuite une erreur assistant inconnu.

Quotas

Chaque assistant créé consomme une instance de votre formule. Si le plafond est atteint : 403 avec {"code":"AGENT_QUOTA","quota":"instances",…}. Les quotas sources, segments et messages s'appliquent par assistant comme pour la clé d'assistant.

3. Converser avec le chatbot

Clé d'assistant ak_… uniquement. Avec une clé compte, interrogez via l'URL publique public_predict_url ou générez une clé d'assistant par assistant (api_key dans la réponse POST /agents).

POST/chat

curl https://www.achatbot.eu/console/api/client/chat \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Quels sont vos délais de livraison ?",
    "sessionId": "utilisateur-123"
  }'

Réponse :

{
  "text": "Les délais de livraison sont de 3 à 5 jours ouvrables…",
  "sourceDocuments": [
    {
      "pageContent": "…",
      "metadata": {
        "source_file": "faq.pdf",
        "display_title": "FAQ livraison",
        "product_url": "https://www.exemple.com/produit/guide",
        "cta_label": "Acheter le guide"
      }
    }
  ]
}

sessionId (optionnel) maintient la mémoire de conversation côté serveur : utilisez un identifiant stable par utilisateur ou par conversation. history (recommandé pour les relances ; rôles userMessage / apiMessage) ancre la recherche documentaire sur le tour précédent (ex. « je peux avoir les réponses » après un quiz). Si history est omis avec un sessionId déjà connu, la console recharge les tours précédents de la session. lang (optionnel, ex. "nl") fixe la langue de repli de la réponse.

Cet endpoint applique le même traitement que la fenêtre de chat et l'espace de test de la console : à corpus et configuration identiques, vous obtenez la même réponse dans les deux canaux.

Les métadonnées commerciales product_url et cta_label (définies via PATCH /sources/:id ou la console) sont renvoyées dans sourceDocuments[].metadata lorsque la source citée en possède. Même comportement sur POST /agents/:slug/chat, le predict public et le MCP achatbot_agent_chat. Le catalogue public (GET …/public/agents/:slug/config → source_catalog) les expose aussi pour les intégrations iframe / widget.

Exemple Node.js

const resp = await fetch("https://www.achatbot.eu/console/api/client/chat", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CHATBOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ question, sessionId: userId }),
});
const { text, sourceDocuments } = await resp.json();

4. Gérer vos sources de données

Clé d'assistant ak_… uniquement — ou préfixe /agents/:slug avec une clé compte (section 2 bis).

GET/sources — lister vos documents

curl -H "Authorization: Bearer $API_KEY" \
  https://www.achatbot.eu/console/api/client/sources

{
  "agent": "votre-chatbot",
  "total_chunks": 42,
  "sources": [
    { "id": 3, "filename": "faq.pdf", "chunks": 12, "status": "indexed",
      "updated_at": "2026-06-12T08:00:00.000Z" }
  ]
}

POST/sources — uploader & indexer un PDF

Le document est découpé, vectorisé et immédiatement interrogeable. Ré-uploader un fichier du même nom remplace l'ancien contenu.

curl -H "Authorization: Bearer $API_KEY" \
  -F "file=@catalogue-2026.pdf" \
  https://www.achatbot.eu/console/api/client/sources

{ "id": 4, "filename": "catalogue-2026.pdf", "chunks": 18, "replaced": false }

POST/sources/text — indexer un bloc de texte

Pour les contenus sans fichier : FAQ, conditions, descriptions produits… Renvoyer le même titre remplace le contenu précédent. Pour des paires question/réponse, préférer /sources/qa (un contenu au format « Question : … / Réponse : … » envoyé ici est toutefois routé automatiquement en Q&A).

curl -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "title": "Conditions générales",
    "content": "Article 1. Les présentes conditions…"
  }' \
  https://www.achatbot.eu/console/api/client/sources/text

POST/sources/qa — indexer une source Q&A

Crée une source de type Q&A (badge violet, paires dépliables). Accepte entries[] structurées, ou un content au format « Question : … / Réponse : … ».

curl -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "title": "autoevaluation-ch1",
    "display_title": "Q&A — autoévaluation personnelle",
    "entries": [
      { "question": "Pourquoi l'\''autoévaluation est-elle critique ?", "answer": "Parce que…" }
    ]
  }' \
  https://www.achatbot.eu/console/api/client/sources/qa

POST/sources/web — absorber un site web

Crawle un site ou indexe une liste d'URLs. Options :

curl -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.exemple.be/page-1",
      "https://www.exemple.be/page-2"
    ]
  }' \
  https://www.achatbot.eu/console/api/client/sources/web

{ "id": 5, "filename": "web:exemple.be", "type": "web", "pages": 23, "chunks": 117 }

POST/sources/youtube — indexer une chaîne YouTube

Indexe les transcripts des ~15 dernières vidéos de la chaîne. Accepte un @handle, une URL de chaîne, un nom ou un ID UC….

curl -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "channel": "@MaChaine" }' \
  https://www.achatbot.eu/console/api/client/sources/youtube

{ "id": 6, "filename": "youtube:Ma Chaîne", "type": "youtube",
  "videos_indexed": 14, "videos_sans_transcript": 1, "chunks": 312 }

POST/sources/wordpress — indexer un site WordPress

Ingère tous les articles publiés via l'API REST WordPress (wp-json/wp/v2/posts). Accepte l'URL du site (recommandé) ou l'endpoint REST complet. Les gros sites partent en indexation asynchrone (status: indexing). Nécessite la fonctionnalité crawl web de la formule.

Pour trouver la bonne URL : collez d'abord l'adresse d'accueil (https://www.exemple.com). Pour vérifier l'API, ouvrez https://www.exemple.com/wp-json/wp/v2/posts — du JSON doit s'afficher. Sous-dossier : https://www.exemple.com/blog/…. Évitez les URLs d'article isolé et /wp-admin.

curl -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://www.exemple.com", "display_title": "Mon blog", "auto_refresh": true }' \
  https://www.achatbot.eu/console/api/client/sources/wordpress

{ "id": 7, "filename": "wordpress:exemple.com", "type": "wordpress",
  "total_posts": 2438, "async": true, "status": "indexing" }

POST/sources/:id/refresh — récupérer les nouveautés

YouTube : indexe les nouvelles vidéos publiées depuis la dernière vérification (un contrôle automatique quotidien est aussi en place). WordPress : indexe les nouveaux articles depuis la dernière sync. Web : relance le crawl complet.

curl -X POST -H "Authorization: Bearer $API_KEY" \
  https://www.achatbot.eu/console/api/client/sources/6/refresh

POST/sources/:id/reindex — réindexer

Purge les vecteurs de cette source et la ré-indexe depuis l'original (fichier stocké, re-crawl du site ou re-téléchargement des transcripts).

curl -X POST -H "Authorization: Bearer $API_KEY" \
  https://www.achatbot.eu/console/api/client/sources/4/reindex

DELETE/sources/:id — supprimer

curl -X DELETE -H "Authorization: Bearer $API_KEY" \
  https://www.achatbot.eu/console/api/client/sources/4

5. Suivre votre usage

GET/usage?month=2026-06

{
  "agent": "votre-chatbot",
  "month": "2026-06",
  "usage": { "user_messages": 412, "bot_messages": 412, "sessions": 187 },
  "total": { "user_messages": 1532, "sessions": 704 }
}

6. Codes d'erreur

7. Afficher le chatbot sur votre site (sans clé)

Option A — iframe (page de chat complète)

<iframe
  src="https://www.achatbot.eu/console/chat.html?agent=VOTRE-CHATBOT&lang=nl"
  style="width:100%;height:640px;border:none;border-radius:12px"
></iframe>

La page reprend automatiquement votre configuration : titre, message d'accueil, couleurs, suggestions, disclaimer et mode vocal.

Langue (&lang=) : message d'accueil, disclaimer, placeholder, suggestions et libellés CTA commerciaux des sources sont traduits automatiquement dans la langue demandée (nl, en, de, en-US…, toute langue acceptée — première demande traduite à la volée puis mise en cache). Pour les livres, si des éditions alternatives sont documentées (titre + URL par langue), le titre et le lien commercial de citation suivent aussi ?lang=. Sans paramètre, la langue du navigateur du visiteur est utilisée. Le chatbot répond par ailleurs toujours dans la langue dans laquelle l'utilisateur écrit (consigne plateforme prioritaire, même si le prompt métier demande une autre langue), et le mode vocal (dictée + lecture) suit la langue active. Le titre du chatbot (nom de marque) n'est jamais traduit.

Option B — widget bulle de chat (recommandé)

Bulle en bas à droite du site ; ouvre une modale avec la page de chat complète (titre, couleurs, suggestions, mode vocal). Aucune clé API dans le navigateur.

Formule Professionnel ou Entreprise : le widget charge automatiquement la bannière de consentement cookies (RGPD) avant d'afficher le chat. Preuves enregistrées côté serveur avec le scope agent:VOTRE-CHATBOT.

<script src="https://www.achatbot.eu/console/widget.js"></script>
<script>
  AkiChat.init({ agent: "VOTRE-CHATBOT" });
</script>

Langue fixe pour accueil / disclaimer / suggestions : AkiChat.init({ agent: "…", lang: "nl" });

Accueil personnalisé dans la modale (style « composer-first ») : passez le prénom du visiteur avec visitorName — affiché comme « À vous la parole, … » avant la première question. Les bulles d'accroche (widget_teasers) ouvrent le chat et envoient directement la question.

AkiChat.init({
  agent: "VOTRE-CHATBOT",
  lang: "fr",
  visitorName: "Marie"
});

Sur desktop, la modale peut être agrandie en tirant le coin supérieur gauche (largeur × hauteur). La taille choisie est mémorisée pour la session du navigateur (sessionStorage, clé par agent) et réappliquée aux prochaines ouvertures.

Page standalone (lien direct, sans embed) : https://www.achatbot.eu/console/chat.html?agent=VOTRE-CHATBOT

Option C — interface sur mesure (API publique)

Si vous ne voulez ni iframe ni bulle, construisez votre propre UI en deux appels publics (CORS ouvert, sans clé) :

1. GET …/api/public/agents/VOTRE-CHATBOT/config?lang=fr — titre, couleurs, accueil, disclaimer (disclaimer_position : top sous le titre, bottom sous la zone de saisie en petit texte), ai_notice (bandeau ouverture, non masquable), ai_footer_label (pied permanent), privacy_url, model_outside_eu + model_outside_eu_notice si modèle hors UE, suggestions, prediction_url
2. POST …/predict avec { "question", "streaming": true, "chatId", "history", "deploymentUrl" } — réponse JSON ou flux SSE (event: token, sourceDocuments, replace si anti-hallucination). deploymentUrl est optionnel et permet d'identifier un site qui appelle encore un agent archivé. Celui-ci répond 503 AGENT_ARCHIVED. Une 2^e prédiction pour le même chatId pendant une génération en cours répond 429 PREDICT_IN_FLIGHT. Dans chat.html / le widget, envoyer un message pendant le streaming arrête la génération puis envoie le nouveau texte. L'iframe, le widget et les aperçus console partagent le même indicateur de réflexion à trois points. Un tableau dans la réponse affiche un lien de téléchargement Excel (.xls).

Exemple minimal : voir site/public/home-chat.js sur www.achatbot.eu (chat démo above-the-fold). Le champ chatId (UUID stable par visiteur) remplace sessionId de l'API client.

Look recommandé (best practice) — pour coller à la fenêtre de chat production (iframe / widget / aperçus console) :

• Appliquer primaryColor (ou accent) de la config comme couleur d’accent des bulles et du bouton d’envoi.
• Bouton d’envoi : cercle plein (≈ 36×36 px), icône avion papier blanche (pas une flèche haut générique) :

<button type="submit" class="send-btn" aria-label="Envoyer"
  style="width:36px;height:36px;border-radius:50%;border:none;background:VAR(--accent);color:#fff;display:grid;place-items:center">
  <svg class="icon-send" viewBox="0 0 24 24" width="17" height="17" aria-hidden="true"
    style="fill:currentColor">
    <path d="M3.4 20.4 20.85 12 3.4 3.6l-.01 6.53L15 12 3.39 13.87z"/>
  </svg>
</button>

Préférez l’iframe ou le widget si vous voulez cette UI sans la maintenir : ils chargent chat.html et restent alignés avec les mises à jour.

8. MCP — piloter depuis Cursor ou Claude Desktop

Le serveur MCP est distribué sur npm sous le nom achatbot-mcp. Il expose des outils pour gérer vos chatbots via l'API client : sources, paramètres organisation et assistant, déploiement (iframe / widget) et historique de conversations. Aucun clone Git requis.

Prérequis

• Node.js 18+
• Formule Business+ (API activée — accès sécurisé derrière votre login)
• Clé compte ak_account_… — tableau de bord → Clés API → Clé compte API (recommandé pour multi-assistants)
• Ou clé d'assistant ak_… + slug pour un seul chatbot

Installation (npx)

npx -y achatbot-mcp

La première exécution télécharge le package depuis le registre npm public.

Configuration Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "achatbot": {
      "command": "npx",
      "args": ["-y", "achatbot-mcp"],
      "env": {
        "ACHATBOT_BASE_URL": "https://www.achatbot.eu",
        "ACHATBOT_ACCOUNT_KEY": "ak_account_VOTRE_CLE"
      }
    }
  }
}

Claude Desktop : même principe (command + args + variables d'environnement).

Sur macOS, si Cursor ou Claude Desktop ne trouve pas npx au démarrage du serveur MCP (command not found), utilisez le chemin absolu renvoyé par which npx dans le terminal : par ex. /opt/homebrew/bin/npx (Apple Silicon) ou /usr/local/bin/npx (Intel), à la place de npx dans command.

Outils disponibles (extrait v3)

Package npm : achatbot-mcp · API sous-jacente : section 2 bis (clé compte) ci-dessus.

ACHATBOT.EU — www.achatbot.eu · Données hébergées en Union européenne · Support : formulaire de contact · Gérer les cookies