Aller au contenu
Dashboard

Bases de connaissances

Lister les bases de connaissances de tes agents, chercher dans l'une exactement comme l'agent, gérer ses réponses, et lire ou réécrire ses fichiers.

Une base de connaissances est ce dans quoi un agent cherche avant de répondre : ton site, tes fichiers et tes réponses. L’API lit chaque base, y cherche comme le fait l’agent, gère ses réponses, et lit et réécrit ses fichiers texte.

Méthode Chemin Scope
GET /knowledge-bases knowledge:read
GET /knowledge-bases/{id} knowledge:read
GET /knowledge-bases/{id}/search knowledge:read
GET /knowledge-bases/{id}/answers knowledge:read
POST /knowledge-bases/{id}/answers knowledge:write
PATCH /knowledge-bases/{id}/answers/{answerId} knowledge:write
DELETE /knowledge-bases/{id}/answers/{answerId} knowledge:write
GET /knowledge-bases/{id}/files/{fileId} knowledge:read
POST /knowledge-bases/{id}/files knowledge:write
PATCH /knowledge-bases/{id}/files/{fileId} knowledge:write
DELETE /knowledge-bases/{id}/files/{fileId} knowledge:write

Un agent répond à partir d’une seule base à la fois. GET /campaigns la donne dans knowledge_base_id, sur chaque campagne.

GET /knowledge-bases liste les bases de l’espace. GET /knowledge-bases/{id} ajoute le détail d’une base : chaque site, chaque fichier et le nombre de réponses.

Terminal window
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10" \
-H "Authorization: Bearer ws_live_…"
{
"data": {
"id": "68c1f1c4001a09be5d10",
"name": "Acme France",
"campaign_ids": ["66f1a2b3c4d5e6f7a8b9c0c1"],
"created_at": "2026-09-02T09:19:48.000+00:00",
"sources": [
{ "id": "68c1f1d80033a1b07c55", "kind": "website", "name": "acme.fr", "status": "ready", "created_at": "2026-09-02T09:20:08.000+00:00", "url": "https://acme.fr", "pages_read": 12, "pages_found": 13, "last_read_at": "2026-10-05T03:17:02.000+00:00" },
{ "id": "68d40b7e000f1c2d3a66", "kind": "file", "name": "tarifs-2026.pdf", "status": "ready", "created_at": "2026-09-24T15:02:54.000+00:00", "pages": 3, "size_bytes": 184220, "editable": false },
{ "id": "68e61c2a0019f0a4d3b1", "kind": "file", "name": "horaires.txt", "status": "ready", "created_at": "2026-10-09T08:40:10.000+00:00", "pages": null, "size_bytes": 77, "editable": true },
{ "id": null, "kind": "answers", "name": null, "status": "ready", "created_at": "2026-09-03T08:11:40.000+00:00", "answers": 14 }
],
"answers_limit": 200,
"can_add_answers": true,
"files_limit": 5,
"can_add_files": true
}
}
Champ Signification
campaign_ids Les agents qui répondent à partir de cette base : l’id de GET /campaigns.
sources[].kind website, file ou answers. Toutes les réponses d’une base se lisent comme une seule source.
sources[].status ready (l’agent peut s’en servir), reading (lecture en cours), failed (n’a pas pu être lue) ou empty (rien de lisible dedans).
answers_limit Le nombre de réponses que la base peut contenir avec ton forfait.
sources[].editable Fichiers seulement. true pour un fichier texte (.txt, .md) : son texte peut être réécrit par l’API. false pour un PDF ou un fichier Word, que l’API lit et retire.
can_add_answers false sur un forfait qui lit ses connaissances mais n’en ajoute pas.
files_limit, can_add_files La même chose pour les fichiers : combien la base peut en contenir avec ton forfait, et si ton forfait en ajoute.

Dans la liste, sources est un compte par type : { "websites": 1, "files": 2, "answers": 14 }. La liste n’a pas de curseur.

La recherche renvoie les passages que l’agent reçoit quand un prospect écrit un message. C’est la même recherche qu’au moment de répondre, avec les mêmes limites : 4 passages au plus, seulement ceux qui sont assez proches du message, et seuls les 500 derniers caractères du message comptent.

Terminal window
curl -G "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/search" \
--data-urlencode "query=c'est combien la séance d'essai ?" \
-H "Authorization: Bearer ws_live_…"
{
"data": {
"query": "c'est combien la séance d'essai ?",
"matched": true,
"reason": null,
"results": [
{ "text": "Q: Combien coûte la séance d'essai ?\nA: La séance d'essai est offerte, sans engagement.", "source": "Q&A", "score": 0.812 },
{ "text": "Les abonnements commencent à 39 EUR par mois. La première séance est offerte à chaque nouveau membre.", "source": "tarifs-2026.pdf", "score": 0.547 }
]
}
}
Champ Signification
query Le texte qui a été cherché : les 500 derniers caractères de ce que tu as envoyé.
matched false quand l’agent ne reçoit rien de la base pour ce message. Il répond alors avec son prompt seul.
reason Pourquoi rien n’a été trouvé : no_match (rien d’assez proche), empty (la base ne contient encore rien) ou inactive. null quand un passage a été trouvé.
results[].source D’où vient le passage : un nom de fichier, une page, ou Q&A pour l’une de tes réponses.
results[].score La proximité avec le message, de 0 à 1. Le meilleur en premier.

Elle sert à deux choses : voir ce qu’un agent a reçu quand il a écrit une réponse, et vérifier qu’une réponse que tu viens d’ajouter est bien trouvée. Seules les réponses cherchent dans la base. Le premier message et les relances ne le font pas.

Une réponse est une question et sa réponse, la même chose que Tes réponses dans le dashboard. C’est ce qu’un agent peut savoir de plus précis : quand un prospect pose la question, l’agent reçoit la réponse.

Terminal window
curl -X POST "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/answers" \
-H "Authorization: Bearer ws_live_…" \
-H "Content-Type: application/json" \
-d '{
"question": "Combien coûte la séance d’essai ?",
"answer": "La séance d’essai est offerte, sans engagement."
}'
{
"data": {
"id": "68e3a90f0026d1e4b7a2",
"question": "Combien coûte la séance d’essai ?",
"answer": "La séance d’essai est offerte, sans engagement.",
"created_at": "2026-10-08T14:20:05.000+00:00",
"updated_at": "2026-10-08T14:20:05.000+00:00"
}
}
Appel Ce qu’il fait
GET /knowledge-bases/{id}/answers Liste les réponses, de la plus récente à la plus ancienne, avec un curseur.
POST /knowledge-bases/{id}/answers Ajoute une réponse. Répond 201.
PATCH /knowledge-bases/{id}/answers/{answerId} Change question, answer, ou les deux. Le texte précédent n’est pas gardé.
DELETE /knowledge-bases/{id}/answers/{answerId} Retire la réponse. Répond 204, puis 404 si tu l’appelles de nouveau.

question contient de 1 à 1000 caractères et answer de 1 à 4000. Un texte plus long est refusé, jamais coupé. Les agents qui répondent à partir de la base utilisent le changement dès leur prochaine réponse.

GET /knowledge-bases/{id} liste les fichiers d’une base. Chacun a un id, et editable dit si son texte peut être réécrit par l’API : true pour un fichier texte (.txt, .md), false pour un PDF ou un fichier Word.

GET /knowledge-bases/{id}/files/{fileId} renvoie le fichier avec tout son texte.

Terminal window
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1" \
-H "Authorization: Bearer ws_live_…"
{
"data": {
"id": "68e61c2a0019f0a4d3b1",
"name": "horaires.txt",
"status": "ready",
"size_bytes": 77,
"pages": null,
"passages": 1,
"editable": true,
"created_at": "2026-10-09T08:40:10.000+00:00",
"updated_at": "2026-10-09T08:40:10.000+00:00",
"text": "Du lundi au vendredi : 7 h à 22 h.\nSamedi : 9 h à 18 h.\nFermé le dimanche.",
"text_source": "file",
"revision": "5f2a9c81d04be637",
"characters": 74,
"offset": 0,
"next_offset": null
}
}
Champ Signification
text Le texte du fichier.
text_source D’où vient le texte. file : le texte enregistré, au caractère près (un fichier .txt, .md ou .csv). passages : reconstitué à partir des passages que l’agent détient (un PDF ou un fichier Word : ses mots, sans sa mise en page, et pas au caractère près, car un mot qui finit un passage et commence le suivant peut revenir deux fois ou une seule). passages_unordered : la même chose, quand l’ordre des passages n’est pas connu.
revision La révision du texte entier, quand text_source vaut file. Renvoie-la dans if_revision quand tu réécris le fichier. null pour un texte reconstitué à partir de passages, et dans le cas rare où une modification a été interrompue sans qu’on puisse dire quel texte a été enregistré (envoie alors le texte entier, sans if_revision).
characters La longueur du texte entier.
next_offset null quand le texte est complet. Sinon, rappelle avec offset à cette valeur : un long texte arrive par fenêtres de limit caractères (100000 par défaut, 200000 au plus).
passages Le nombre de passages que l’agent détient pour ce fichier : ce dans quoi la recherche choisit.

PATCH /knowledge-bases/{id}/files/{fileId} avec edits remplace un texte par un autre à l’intérieur du fichier. Chaque find doit se trouver exactement une fois dans le fichier. S’il manque, ou s’il s’y trouve plusieurs fois, l’appel répond 422 et rien n’est changé. C’est la façon sûre de changer un prix ou un horaire sans toucher au reste.

Terminal window
curl -X PATCH "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1" \
-H "Authorization: Bearer ws_live_…" \
-H "Content-Type: application/json" \
-d '{
"edits": [
{
"find": "Samedi : 9 h à 18 h.",
"replace": "Samedi : 9 h à 20 h."
}
]
}'
{
"data": {
"id": "68e61c2a0019f0a4d3b1",
"name": "horaires.txt",
"status": "ready",
"size_bytes": 77,
"pages": null,
"passages": 1,
"editable": true,
"created_at": "2026-10-09T08:40:10.000+00:00",
"updated_at": "2026-10-09T09:02:31.000+00:00",
"changed": true,
"revision": "c41d7e0a92b3f586",
"characters": 74,
"previous_characters": 74
}
}

Pour remplacer tout le texte, envoie text à la place de edits. Le fichier garde son id et son nom. Les agents utilisent le nouveau texte dès leur prochaine réponse, et ne trouvent jamais le fichier vide entre les deux. Le texte précédent n’est pas gardé : lis le fichier avant si tu peux vouloir le retrouver. Envoyer le texte que le fichier contient déjà répond changed: false.

Envoie une seule modification à la fois pour un fichier donné :

  • Ajoute "if_revision" avec la revision que tu as lue. Si le fichier n’est plus ce texte, l’appel répond 409 et rien n’est modifié : relis-le, puis réessaie.
  • Mets plusieurs remplacements dans une seule liste edits, pas dans plusieurs appels. Deux modifications du même fichier envoyées au même instant ne sont jamais enregistrées toutes les deux : l’une d’elles, ou les deux, répondent 409 et n’enregistrent rien.
  • Une modification envoyée pendant qu’une autre est en cours d’enregistrement répond 409 aussi : attends la réponse de l’autre, relis le fichier, puis réessaie.
  • Un 502 dit dans son message ce que le fichier contient : soit rien n’a été modifié, soit la modification est peut-être appliquée en partie. Dans le second cas le fichier est entre deux textes : pendant une minute et demie toute modification répond 409. Ensuite, relis-le : il renvoie le texte qui a été enregistré. Si ta modification n’y est pas, renvoie-la.
Appel Ce qu’il fait
POST /knowledge-bases/{id}/files Ajoute un fichier texte à partir d’un name et d’un text. Il est lu tout de suite : quand l’appel répond 201, les agents peuvent s’en servir.
PATCH /knowledge-bases/{id}/files/{fileId} Réécrit un fichier texte, avec edits ou avec text.
DELETE /knowledge-bases/{id}/files/{fileId} Retire un fichier, quel que soit son type, avec ce que les agents en ont appris. Répond 204. Il ne peut pas être récupéré.

Un name se termine par .txt ou .md ; sans extension, il reçoit .txt. Une base ne peut pas contenir deux fichiers du même nom : l’appel répond 409 et nomme le fichier à réécrire. Un texte écrit par l’API est découpé en passages exactement comme un fichier envoyé depuis le dashboard.

Un PDF ou un fichier Word ne peut pas être réécrit sur place (409). Le texte que l’API en relit est proche du fichier, pas le fichier au caractère près : remplacer un PDF par ce texte est un choix à faire après l’avoir lu, pas une étape à automatiser. Un fichier encore en cours de lecture (status autre que ready) ne peut être ni réécrit ni retiré pour l’instant (409).

Certaines choses demandent une lecture de site, un envoi de fichier ou un choix fait une fois. Elles se font dans le dashboard, dans Connaissances :

  • créer une base et la relier à un agent,
  • ajouter un site et le relire,
  • envoyer un PDF ou un fichier Word,
  • supprimer une base.
Limite Valeur
Réponses par base 200
question 1000 caractères
answer 4000 caractères
Fichiers par base 3, 5 ou 10 selon ton forfait (files_limit)
Texte d’un fichier écrit par l’API 200000 caractères
Nom d’un fichier 120 caractères
edits par appel 50
Passages renvoyés par une recherche 4
Longueur du message qui compte dans une recherche les 500 derniers caractères

Ajouter une réponse ou un fichier demande un forfait payant. Avec l’offre gratuite, tu peux toujours lire, chercher, corriger et retirer ce que la base contient déjà.

HTTP code Quand
401 missing_api_key, invalid_api_key Clé absente, inconnue ou révoquée.
402 plan_limit_reached Ajout d’une réponse ou d’un fichier avec un forfait qui n’ajoute pas de connaissances, ou dans une base qui contient déjà ses 200 réponses ou tous les fichiers que son forfait permet.
403 insufficient_scope Il manque knowledge:read ou knowledge:write à la clé. Une clé créée avant l’existence de ces scopes ne les a pas.
404 not_found Base, réponse ou fichier inconnu, ou d’un autre espace.
409 invalid_state Réécriture d’un fichier qui n’est pas un fichier texte, réécriture ou retrait d’un fichier encore en cours de lecture, ajout d’un fichier dont la base contient déjà le nom, if_revision qui n’est plus celle du fichier, autre modification du même fichier en cours d’enregistrement, ou fichier dont on ne peut pas dire quel texte a été enregistré après une modification interrompue. Rien n’a été modifié.
422 validation_error query absent ou de plus de 2000 caractères, question, answer ou text vide ou trop long, un PATCH sans rien à changer, un nom de fichier qui n’est ni .txt ni .md, un find qui ne se trouve pas exactement une fois dans le fichier.
429 rate_limited Trop de requêtes cette minute. Respecte Retry-After.
502 upstream_error Un stockage n’a pas répondu. Le message dit ce qui s’est passé : rien n’a été modifié, ou la demande est peut-être appliquée en partie, et quoi faire dans ce cas. Relis la base ou le fichier avant de réessayer.