Kennis uit een portal achter een inlog

Een assistent leest je openbare site via een sitemap. Een portal achter een inlog heeft geen sitemap die we mogen lezen. Toch wil je dat de assistent daar de hulp- teksten kent: hoe download je een factuur, waar stel je iets in. Daarvoor zijn er twee wegen. Beide werken zonder dat wij een sessie van een gebruiker nodig hebben, en je portal blijft zelf bepalen wat eruit gaat.

Dit is een handleiding voor wie het portal bouwt. Een ontwikkelaar kan hem zonder ons volgen. De assistent zelf maak je eerst aan, zie Support Studio.

Feed of push

Kies een feed als het portal een lijst kan tonen. Kies een push als het portal zelf weet wanneer er iets verandert. Je mag beide gebruiken. Elke weg heeft zijn eigen bron, en een pad dat in beide voorkomt, staat er dan twee keer in.

Het formaat

Een feed geeft JSON terug, en een push stuurt hetzelfde onder items.

{
  "versie": 1,
  "items": [
    {
      "pad": "/help/facturen",
      "url": "https://portal.voorbeeld.nl/help/facturen",
      "titel": "Facturen downloaden",
      "tekst": "Open Facturatie en kies Downloaden naast de maand ...",
      "categorie": "Facturatie",
      "bijgewerkt": "2026-10-06T10:00:00Z"
    }
  ]
}

Een kale lijst ([ {...} ]) mag ook. De Engelse veldnamen title, text, category en updated worden ook gelezen.

Grenzen

• Hoogstens 2 MB per antwoord of push en hoogstens 500 items. Bij een feed wordt de rest genegeerd, een push met meer wordt geweigerd.
• Een item dat niet klopt, wordt geweigerd met een vaste reden (pad-ongeldig, titel-leeg, tekst-leeg, url-andere-oorsprong, dubbel). De rest gaat gewoon door.
• Een feed moet https zijn. Een feed met sleutel gaat nooit over gewone http.
• Geeft een feed niets of onzin terug, dan blijft de bestaande kennis staan. Een portal dat even stuk is, wist de assistent niet.

Een feed instellen

1. Ga naar Support, Kennis, Portal achter een inlog en vul het https-adres van de feed in. Je krijgt een sleutel (dpf_...). Die staat één keer op het scherm; in de database staat hij versleuteld. Kopieer hem meteen.
2. Zet de sleutel in je portal. Het portal antwoordt alleen als de kop Authorization: Bearer dpf_... klopt, en geeft anders een 401 zonder uitleg.
3. Kies Nu opnieuw lezen. Daarna leest Denkploeg de feed elke nacht.
4. Een nieuwe sleutel maak je met Sleutel draaien. De oude werkt dan niet meer, dus zet de nieuwe meteen in je portal. Tot dat gebeurd is, staat de bron op fout en blijft de kennis staan.

Een bron toont zijn stand: wacht op de eerste keer lezen, gelezen, of een fout met de reden (de feed weigerde de sleutel, was te groot, gaf geen JSON of geen geldige items).

Een push instellen

1. Een eigenaar van het bureau maakt onder Agency, Koppelsleutels een sleutel met het recht Kennis naar een assistent sturen. Dat vinkje staat niet standaard aan. De sleutel (dpb_...) staat één keer op het scherm.
2. Onder Support, Kennis, bij "Of laat het portal zelf sturen" staat een voorbeeld met het id van je assistent erin, en wat je portal het laatst stuurde.
3. Je portal stuurt:

POST /api/bureau/support/kennis
Authorization: Bearer dpb_...

{
  "assistent": "<id van de assistent>",
  "items": [ { "pad": "/help/facturen", "titel": "...", "tekst": "..." } ],
  "verwijder": ["/help/oud"],
  "volledig": false
}

• Een push werkt op pad: een ongewijzigd item blijft staan, een gewijzigd item wordt vervangen.
• verwijder haalt paden weg (hoogstens 500).
• Met volledig: true is items de complete lijst, en alles wat er niet in staat, verdwijnt. Een lege lijst met volledig wordt geweigerd: dat zou alles wissen.
• Bij succes: {"ok":true,"aangepast":2,"ongewijzigd":10,"verwijderd":1,"geweigerd":[]}.

Foutcodes: 401 sleutel-ongeldig, 403 recht-ontbreekt, 404 niet-gevonden (ook voor een assistent van een ander bureau), 400 ongeldige-vraag, 413 te-groot of te-veel-items, 429 te-druk (hoogstens 30 pushes per minuut per sleutel).

De sleutel kan alleen kennis schrijven in de push-bron van die ene assistent, en niets anders. Elke push staat in het auditspoor van het bureau.

De open pagina meesturen

Staat de assistent zelf in dit portal, dan stuurt het script bij elke paginawissel het pad, de titel en de belangrijkste koppen (h1 en h2) mee met de vraag. Alleen die velden: geen query, geen tekst uit formulieren. Zo gaat "hoe werkt dit scherm" over het scherm waar de bezoeker staat. Heeft je feed of push een item met precies dit pad, dan gaat dat item voor in de kennis.

Zorg daarom dat elk scherm een duidelijke <title> en een <h1> heeft, en dat het pad van een item gelijk is aan het pad van dat scherm.

Privacy en veiligheid

• Zet er niets persoonlijks in. Alles in een item kan de assistent aan elke bezoeker vertellen. Dit zijn hulpteksten voor iedereen die het portal gebruikt, geen gegevens van een gebruiker. Een ingelogde gebruiker herken je via Support koppelen, en dat gaat apart.
• Tekst van buiten. Een tekst uit een feed is net zo onvertrouwd als sitetekst. Hij gaat omhuld de assistent in en kan alleen als tekst terugkomen in een chat. Er is geen gereedschap dat iets wijzigt. Een bronlink kan alleen naar de eigen oorsprong wijzen.
• De sleutel staat alleen in de omgeving van je portal, niet in de repo of de logs. Bij een feed gaat de sleutel nooit mee over een omleiding naar een andere oorsprong.
• Ons ophalen weigert interne adressen, heeft een tijdsbudget en een grens op de grootte, en leest alleen JSON.

Klaar als

• De feed geeft met de juiste sleutel 200 en JSON in dit formaat, en 401 zonder of met een verkeerde sleutel (of de push geeft ok: true).
• Elk scherm dat hulp nodig heeft, heeft een item met het pad van dat scherm.
• Er staat niets in dat niet voor elke gebruiker bedoeld is.