Semantic Search voor FreeScout
Semantic Search is een zelfstandige FreeScout-module die zoeken met meerdere woorden oplost en, zodra je je eigen AI-sleutel toevoegt, gesprekken vindt op basis van waar ze over gaan. De module wordt verkocht door de makers van ReplyRabbit, maar ReplyRabbit hoeft niet geïnstalleerd te zijn.
Op zoek naar het overzicht?
Overzicht
De ingebouwde zoekfunctie van FreeScout zoekt je hele zoekopdracht als één frase in één veld. Een zoekopdracht zoals frank invoice vindt niets, omdat de klantnaam op één plek staat en het woord "factuur" ergens anders. Semantic Search vervangt dat gedrag in twee fasen:
- Trefwoordmodus (geen sleutel nodig): elk woord in je zoekopdracht moet ergens in het gesprek voorkomen. Onderwerp, klantnaam, e-mailadres en berichttekst tellen allemaal mee. Dit staat aan zodra de module actief is.
- Zoeken op betekenis (je eigen AI-sleutel): elk gesprek krijgt een compacte vingerafdruk van waar het over gaat, opgeslagen in je FreeScout-database. Een zoekopdracht wordt gematcht op betekenis en op trefwoorden, en de twee lijsten worden gecombineerd zodat het beste antwoord bovenaan komt. Deze modus voedt ook de Vergelijkbare gesprekken paneel in de zijbalk van het gesprek.
De zoekpagina toont een klein Semantisch of Trefwoord label naast het resultaat aantal zodat medewerkers weten welke modus heeft geantwoord.
Zoeksyntaxis
De gebruikelijke zoekmachine-steno werkt in beide modi:
| Je typt | Wat het doet |
|---|---|
frank invoice | Beide woorden moeten ergens in het gesprek voorkomen. |
"out of stock" | De exacte zin moet voorkomen. |
-refund of -"out of stock" | Gesprekken met het woord of de zin worden weggelaten. |
cart OR basket | Eén van beide woorden is genoeg. OR moet in hoofdletters zijn. |
admin@example.com of example.com | Een e-mailadres of domein wordt exact gematcht. |
Zoeken op betekenis voegt alleen gesprekken toe die duidelijk over hetzelfde gaan als de woorden die je hebt getypt. Gequote zinnen, adressen en -exclusions gelden nog steeds voor die resultaten, zodat een zoekopdracht naar een e-mailadres nooit volloopt met ongerelateerde gesprekken.
Zoekbalk en filters
Op de zoekresultatenpagina staat het zoekvak direct naast de Gesprekken en Klanten tabbladen, zodat je een zoekopdracht kunt wijzigen zonder terug te scrollen naar boven. De sorteerkeuzelijst staat rechts van de Klanten tabblad.

Klik op de schuifregelaarknop naast het zoekvak om de Filters paneel. Je hoeft de bovenstaande afkorting niet te onthouden: de vier woordregels schrijven deze voor je in het zoekvak.
| Filter | Wat het schrijft | Wat het doet |
|---|---|---|
| Al deze woorden | frank invoice | Elk woord moet voorkomen. |
| Deze exacte zin | "out of stock" | De woorden moeten samen voorkomen, in deze volgorde. |
| Een van deze woorden | cart OR basket | Eén van de woorden is genoeg. |
| Geen van deze woorden | -refund | Gesprekken met het woord worden weggelaten. |

De standaard FreeScout-filters (mailbox, status, toegewezen, klant, datums en meer) staan in de Geavanceerd sectie onderaan het paneel. Deze is ingeklapt om het paneel kort te houden en opent vanzelf wanneer een van die filters al in gebruik is. Een klein getal op de schuifregelaarknop toont hoeveel filters actief zijn. Klik Toepassen om de zoekopdracht uit te voeren, of Alles wissen om opnieuw te beginnen.

Vanaf 1.1.3, de Klanten tabblad bekijkt elk woord ook afzonderlijk. Als geen enkele klant op elk woord matcht, worden klanten vermeld die op een van de woorden matchen, met de beste matches eerst, zodat invoice frank vindt nog steeds een klant met de naam Frank.
Vereisten
Voordat je begint, zorg dat je het volgende hebt:
- FreeScout 1.8.101 of nieuwer op PHP 8.1 of later.
- Een werkende FreeScout queue worker en scheduler (
php artisan queue:worken deschedule:runcron). Indexering draait daarop. - Een Semantic Search-licentie van je ReplyRabbit-account. De aankoopmail bevat de licentiesleutel.
- Optioneel, voor zoeken op betekenis: een API-sleutel van OpenAI of Google Gemini, of de basis-URL en embedding-modelnaam van een compatibele service zoals OpenRouter, Ollama of LM Studio.
Installeer de module
De ZIP downloaden
Log in op app.replyrabbit.app met het e-mailadres dat je bij het afrekenen hebt gebruikt en open de Semantic Search kaart op het dashboard. Downloadsemantic-search.zip.Kopieer het naar de map Modules
Uitpakkensemantic-search.zipen kopieer deSemanticSearchmap in deModulesmap van je FreeScout-installatie, via SFTP of de bestandsbeheerder van je host, naast de andere modules. FreeScout heeft geen upload in de app voor modules van derden.Activeer de module
Activeren Semantic Search uit de modulelijst. Activering voert de databasemigraties uit die de twee indextabellen aanmaken.Probeer een zoekopdracht
Zoek naar een klantnaam plus een onderwerp, bijvoorbeeld een voornaam en "factuur". De resultaten matchen nu elk woord waar het ook in een gesprek voorkomt, en de zoekpagina toont de Trefwoord label.
Trefwoordmodus werkt op dit punt zonder verdere configuratie. De onderstaande stappen ontgrendelen zoeken op betekenis en het paneel met vergelijkbare gesprekken.
Voer de licentiesleutel in
Open de instellingenpagina
Ga in FreeScout naar Beheren, dan Instellingen, dan Semantic Search.Plak de licentiesleutel
In de Licentie sectie, plak de sleutel uit je aankoopmail en sla op. De status toont Gelicentieerd met het tijdstip van de laatste controle.
De licentie is gekoppeld aan de site-URL van de FreeScout-installatie. Als je FreeScout naar een nieuw domein verplaatst, neem dan contact op met hey@replyrabbit.app en we resetten het.
Stel zoeken op betekenis in
Kies een provider
In de Embedding-provider sectie, kies OpenAI, Google, of OpenAI-compatibel. Het standaardmodel is ingevuld voor OpenAI en Google. Voer voor een compatibele service de basis-URL en de modelnaam in die deze verwacht.Voeg de sleutel toe en test deze
Plak de API-sleutel als je provider er een nodig heeft en klik op Embeddings testen. De test stuurt één korte zin naar het embedding-endpoint en controleert het antwoord. Sleutels worden versleuteld opgeslagen en na opslaan wordt alleen een gemaskeerd voorbeeld getoond.Kies de mailboxen om te indexeren
In de Indexeren sectie, vink de mailboxen aan die je wilt opnemen. Interne notities opnemen staat standaard aan, omdat medewerkers vaak in hun eigen notities zoeken. Stel Backfill-dagen voor hoe ver terug te indexeren (de standaard is 365 dagen).Zoeken op betekenis aanzetten
Vink aan Zoeken op betekenis en sla op. Als de provider, het model of de basis-URL is gewijzigd, meldt de pagina dat gesprekken op de achtergrond opnieuw worden geïndexeerd.Start de eerste index
Klik Nu indexeren. Het statusblok toont voortgang zoals "1.240 van 8.900 geïndexeerd (14%)", de laatste run-tijd, de laatste fout indien aanwezig, en de geschatte resterende kosten. Indexeren gebeurt in batches van ongeveer 200 gesprekken elke vijf minuten, dus een grote desk duurt een paar uur. Zoeken blijft de hele tijd werken.
Welke provider?
Gebruik een aangepast embedding-endpoint
Voer een API-basis-URL in zoals https://embeddings.example.com/v1 of http://10.0.0.25:8001/v1, gevolgd door de exacte embedding-model-ID die daar wordt geserveerd. Semantic Search voegt /embeddings naar de basis-URL. Openbare adressen vereisen HTTPS. Een privé- of loopback-HTTP-adres moet op een vertrouwd netwerk staan dat FreeScout kan bereiken.
Als één gateway zowel chat als embeddings bedient, kun je dezelfde /v1 basis-URL hier en in Aangepaste providerinstellingen van ReplyRabbit. Configureer hier het embedding-model en het chatmodel in ReplyRabbit. Als je chat- en embeddingservers aparte URL's hebben, voer dan elke URL in bij het bijbehorende product. De producten delen geen tokens of instellingen.
De Embeddings testen actie moet een embedding-vector retourneren. Een chatmodel dat alleen antwoordt /chat/completions kan zoeken op betekenis niet aandrijven. Het wijzigen van het endpoint of model start een nieuw indexprofiel; het wijzigen van alleen het token behoudt de bestaande vectoren.


Up-to-date houden
Wanneer een nieuwe versie wordt uitgebracht, toont FreeScout die op Beheren, dan Modules, en Nu bijwerken installeert deze ter plaatse: geen SFTP, geen opnieuw uploaden. De ZIP die je uit je dashboard hebt gedownload bevat de downloadlink van je eigen licentie, dus de update wordt opgehaald achter dezelfde licentiecontrole als de eerste download.
Twee dingen om te weten:
- De update werkt alleen voor een kopie die je van je dashboard hebt gedownload, en je moet je kopie niet doorgeven: de updatelink bevat de downloadsleutel van je eigen licentie, dus iedereen met de ZIP kan updates op jouw licentie ophalen. Een kopie van iemand anders is aan hun licentie gebonden en werkt bij met hun sleutel.
- Als FreeScout een downloadfout meldt, download dan de nieuwe ZIP uit je dashboard en vervang de map handmatig, zoals in de installatiestappen hierboven. Je index en instellingen blijven behouden: ze staan in de database, niet in de modulemap.
Kosten
Indexeren stuurt de tekst van elk gesprek één keer naar je provider, en opnieuw als het gesprek een nieuw antwoord krijgt. Zoeken stuurt alleen de zoekwoorden.
| Provider | Model | Prijs | Ongeveer 100 gesprekken |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 0,02 USD per miljoen tokens | ongeveer 0,01 USD |
| Google Gemini | gemini-embedding-001 | gratis tier, daarna prijs per token | meestal gratis |
| Ollama of LM Studio | elk embedding-model | geen | geen |
De instellingenpagina toont een schatting voor de gesprekken die nog op indexering wachten, zodat je het aantal kunt controleren voordat je klikt Nu indexeren. Opnieuw indexeren gebeurt alleen wanneer je de provider of het model wijzigt, of op Alles opnieuw indexeren.
Paneel Vergelijkbare gesprekken
Met zoeken op betekenis aan, een Vergelijkbare gesprekken paneel verschijnt in de zijbalk van het gesprek. Het toont andere gesprekken in dezelfde mailbox die over hetzelfde gaan, met het onderwerp, de klantnaam en de datum. Medewerkers zien alleen gesprekken waartoe ze al toegang hebben.
Zet het paneel voor iedereen uit met de Vergelijkbare gesprekken schakelaar op de instellingenpagina. Een nieuw gesprek toont "Nothing similar yet" totdat het is geïndexeerd, wat een paar minuten duurt.

Opdrachtregel
Twee commando's helpen wanneer je FreeScout via SSH beheert:
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status toont dezelfde dekkingscijfers als de instellingenpagina. reindex voert direct een batch uit in plaats van te wachten op de scheduler, wat handig is voor de eerste index op een grote desk.
Probleemoplossing
| Symptoom | Wat te controleren |
|---|---|
| De zoekpagina toont Trefwoord in plaats van Semantisch | Bevestigen Zoeken op betekenis is aangevinkt, is de licentiestatus Gelicentieerd, en het statusblok toont geen recente fout. Als de sleutel is mislukt, valt zoeken terug op trefwoordmodus totdat het is opgelost. |
| Er wordt helemaal geen label op de zoekpagina getoond | De zoekopdracht is doorgegeven aan FreeScout's eigen zoekfunctie. Dit gebeurt bij zoekopdrachten die alleen een nummer zijn (ticket- of ordernummers), die de kern al goed afhandelt. |
| Embeddings testen mislukt | Controleer of de sleutel geen voorloop- of volgspaties heeft en bij de juiste provider hoort. Voor een compatibele service bevestig je dat de basis-URL bereikbaar is vanaf de FreeScout-server en dat de naam van het embedding-model precies is wat de service verwacht. |
| Status zegt "Nog niets geïndexeerd" | Zorg ervoor dat de queue worker en de scheduler-cron draaien. Klik op Nu indexeren en ververs na een minuut. Op shared hosting kan de eerste batch een paar minuten duren voordat deze start. |
| Indexeren stopt halverwege | Lees de laatste fout in het statusblok. Rate limits en quota-fouten van de provider zijn de gebruikelijke oorzaak; indexering hervat bij de volgende geplande run. |
| Zoekresultaten zijn traag op een zeer grote helpdesk | Trefwoordmodus controleert elk zoekwoord tegen de berichttekst, wat zwaarder is dan de enkele frase-match van de core. Houd zoekopdrachten beperkt tot een paar woorden, of beperk de mailboxen die in de indexering worden opgenomen. |
| Paneel Vergelijkbare gesprekken is leeg | Het gesprek is nog niet geïndexeerd, of het paneel is uitgeschakeld in de instellingen. Nieuwe gesprekken worden binnen een paar minuten geïndexeerd. |
Privacy en gegevensverwerking
Trefwoordzoeken draait volledig binnen je FreeScout-database en verzendt niets. Met zoeken op betekenis ingeschakeld wordt de tekst van elk geïndexeerd gesprek (onderwerp, klantberichten, antwoorden van medewerkers en interne notities indien inbegrepen) naar de door jou geconfigureerde provider verzonden. Een openbaar endpoint gebruikt HTTPS; een privé HTTP-endpoint blijft op het netwerk dat je configureert. De sleutel is optioneel voor een compatibel endpoint. Alleen de geretourneerde fingerprint wordt opgeslagen.
Het enige contact met replyrabbit.app is de licentiecontrole, die de licentiesleutel, de FreeScout-site-URL en de moduleversie verstuurt. Er worden geen gesprekstekst, zoekwoorden of klantgegevens naar ons verzonden.
Als gesprekstekst op je eigen servers moet blijven, gebruik dan een lokale provider of een compatibel endpoint op je vertrouwde privénetwerk, of blijf in trefwoordmodus. Met een compatibel openbaar endpoint gaat tekst via HTTPS. Privé-HTTP-endpoints zijn alleen toegestaan op een vertrouwd netwerk.
FAQ
Heb ik ReplyRabbit nodig om Semantic Search te gebruiken?
Nee. Semantic Search is een aparte FreeScout-module van dezelfde makers. Het installeert en draait op zichzelf. ReplyRabbit is alleen waar je het koopt, downloadt en de licentiesleutel beheert.
Werkt Semantic Search zonder AI-sleutel?
Ja. Trefwoordmodus is actief vanaf het moment dat je de module activeert, zonder sleutel en zonder instellingen. Elk woord in je zoekopdracht moet ergens in het gesprek voorkomen, in het onderwerp, de klantnaam, het e-mailadres of de berichttekst. De AI-sleutel voegt alleen zoeken op betekenis en het paneel met vergelijkbare gesprekken toe.
Welke AI-providers kan ik gebruiken?
OpenAI (standaard text-embedding-3-small), Google Gemini (standaard gemini-embedding-001), of een OpenAI-compatibele service zoals OpenRouter, Ollama of LM Studio waarbij je zelf de basis-URL en het model invoert. Z.AI wordt niet ondersteund omdat het geen embeddings-service heeft.
Hoeveel kost de AI-sleutel?
Met OpenAI text-embedding-3-small tegen 0,02 USD per miljoen tokens kost het indexeren van ongeveer 100 gesprekken ruwweg 0,01 USD. Een desk met 10.000 gesprekken betaalt ongeveer 1 USD om alles één keer te indexeren, daarna een paar cent per maand voor nieuwe mail. De instellingenpagina toont een schatting voordat de eerste indexering draait.
Waar worden de zoekgegevens opgeslagen?
In twee tabellen in je bestaande FreeScout-database. Elk geïndexeerd gesprek voegt ongeveer een halve kilobyte toe. Er is geen aparte zoekserver nodig en niets wordt op replyrabbit.app opgeslagen.
Werkt het op PostgreSQL?
Ja. Trefwoordzoekopdrachten en zoeken op betekenis werken beide op MySQL, MariaDB en PostgreSQL.
Wat gebeurt er als mijn sleutel stopt met werken of de licentie verloopt?
Zoeken valt zelf terug op trefwoordmodus, zodat agents resultaten blijven krijgen. De instellingenpagina toont de reden. Trefwoordzoekopdrachten zijn nooit afhankelijk van de licentie of de sleutel.