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 A Chatbot .EU :

Les clés peuvent être révoquées à tout moment depuis la console admin.

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é agent, obtenez le slug et les URLs publiques. Avec une clé compte, obtenez la liste de vos agents.

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

Réponse clé agent :

{
  "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-agents (clé compte)

Pour créer un chatbot par formation, produit ou espace (isolation des corpus), demandez une clé compte ak_account_… (console → Paramètres client de l'organisation → section « Clé compte API »). Les endpoints /chat et /sources sans préfixe /agents/:slug restent réservés aux clés agent ak_….

Tableau des endpoints (clé compte)

GET/me — réponse clé compte

{
  "scope": "account",
  "client": "mon-organisation",
  "client_name": "Mon organisation",
  "agents_count": 2,
  "agents": [
    {
      "agent": "assistant-formation-a",
      "title": "Assistant — Formation A",
      "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",
      "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.

Réponse 201 :

{
  "agent": "assistant-ma-formation",
  "title": "Assistant — Ma formation",
  "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)

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": "…", "audience": "en_formation", "suggestions": [] },
  "sources": {
    "total_chunks": 42,
    "items": [
      {
        "id": 102,
        "type": "instructions",
        "filename": "texte:__instructions__",
        "display_title": "Consigne pédagogique",
        "chunks": 3,
        "status": "indexed",
        "editable": true,
        "content_preview": "Formation : … Public visé : …"
      }
    ]
  },
  "usage": { "month": "2026-06", "user_messages": 12, "sessions": 8 }
}

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","suggestions":["…","…"]}}' \
  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 agent

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

# 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'agent, ses vecteurs, ses sources et ses clés. L'URL chat_page_url renvoie ensuite une erreur agent inconnu.

Quotas

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

3. Converser avec le chatbot

Clé agent ak_… uniquement. Avec une clé compte, interrogez via l'URL publique public_predict_url ou générez une clé agent par agent (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" } }
  ]
}

sessionId (optionnel) maintient la mémoire de conversation côté serveur : utilisez un identifiant stable par utilisateur ou par conversation.

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é agent 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.

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/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/: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). 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 et suggestions 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). 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, 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" });

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), suggestions, prediction_url
2. POST …/predict avec { "question", "streaming": true, "chatId", "history" } — réponse JSON ou flux SSE (event: token, sourceDocuments)

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.

A Chatbot .EU — www.achatbot.eu · Données hébergées en Union européenne · Support : formulaire de contact