Guides par ressource
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.
Endpoints
Section intitulée « Endpoints »| 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.
Lister les bases et leurs sources
Section intitulée « Lister les bases et leurs sources »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.
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10" \ -H "Authorization: Bearer ws_live_…"const res = await fetch( 'https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10', { headers: { Authorization: 'Bearer ws_live_…' } },);const { data: base } = await res.json();import requests
r = requests.get( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10", headers={"Authorization": "Bearer ws_live_…"},)base = r.json()["data"]{ "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.
Chercher comme l’agent
Section intitulée « Chercher comme l’agent »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.
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_…"const url = new URL('https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/search');url.searchParams.set('query', "c'est combien la séance d'essai ?");const res = await fetch(url, { headers: { Authorization: 'Bearer ws_live_…' } });const { data } = await res.json();import requests
r = requests.get( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/search", params={"query": "c'est combien la séance d'essai ?"}, headers={"Authorization": "Bearer ws_live_…"},)data = r.json()["data"]{ "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.
Gérer les réponses
Section intitulée « Gérer les réponses »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.
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." }'const res = await fetch( 'https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/answers', { method: 'POST', headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' }, body: JSON.stringify({ question: 'Combien coûte la séance d’essai ?', answer: 'La séance d’essai est offerte, sans engagement.', }), },);const { data: answer } = await res.json();import requests
r = requests.post( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/answers", headers={"Authorization": "Bearer ws_live_…"}, json={ "question": "Combien coûte la séance d’essai ?", "answer": "La séance d’essai est offerte, sans engagement.", },)answer = r.json()["data"]{ "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.
Lire et réécrire un fichier
Section intitulée « Lire et réécrire un fichier »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.
Lire un fichier en entier
Section intitulée « Lire un fichier en entier »GET /knowledge-bases/{id}/files/{fileId} renvoie le fichier avec tout son texte.
curl "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1" \ -H "Authorization: Bearer ws_live_…"const res = await fetch( 'https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1', { headers: { Authorization: 'Bearer ws_live_…' } },);const { data: file } = await res.json();import requests
r = requests.get( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1", headers={"Authorization": "Bearer ws_live_…"},)file = r.json()["data"]{ "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. |
Changer un seul endroit dans un fichier texte
Section intitulée « Changer un seul endroit dans un fichier texte »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.
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." } ] }'const res = await fetch( 'https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1', { method: 'PATCH', headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' }, body: JSON.stringify({ edits: [{ find: "Samedi : 9 h à 18 h.", replace: "Samedi : 9 h à 20 h." }], }), },);const { data: file } = await res.json();import requests
r = requests.patch( "https://app.whatsetter.com/api/v1/knowledge-bases/68c1f1c4001a09be5d10/files/68e61c2a0019f0a4d3b1", headers={"Authorization": "Bearer ws_live_…"}, json={"edits": [{"find": "Samedi : 9 h à 18 h.", "replace": "Samedi : 9 h à 20 h."}]},)file = r.json()["data"]{ "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 larevisionque tu as lue. Si le fichier n’est plus ce texte, l’appel répond409et 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épondent409et n’enregistrent rien. - Une modification envoyée pendant qu’une autre est en cours d’enregistrement répond
409aussi : attends la réponse de l’autre, relis le fichier, puis réessaie. - Un
502dit 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épond409. Ensuite, relis-le : il renvoie le texte qui a été enregistré. Si ta modification n’y est pas, renvoie-la.
Ajouter ou retirer un fichier
Section intitulée « Ajouter ou retirer un fichier »| 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).
Ce qui reste dans le dashboard
Section intitulée « Ce qui reste dans le dashboard »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à.
Les erreurs que tu rencontreras
Section intitulée « Les erreurs que tu rencontreras »| 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. |