Semantic Search for FreeScout
Semantic Search is a standalone FreeScout module that fixes multi-word search and, once you add your own AI key, finds conversations by what they are about. It is sold by the makers of ReplyRabbit but does not need ReplyRabbit installed.
Looking for the overview?
Overview
FreeScout's built-in search looks for your whole query as one phrase in one field. A search like frank invoice finds nothing, because the customer name is in one place and the word "invoice" is in another. Semantic Search replaces that behaviour in two stages:
- Keyword mode (no key needed): every word in your search must appear somewhere in the conversation. Subject, customer name, email address, and message text all count. This is on as soon as the module is active.
- Search by meaning (your own AI key): each conversation gets a compact fingerprint of what it is about, stored in your FreeScout database. A search is matched on meaning and on keywords, and the two lists are blended so the best answer comes first. This mode also powers the Similar conversations panel in the conversation sidebar.
The search page shows a small Semantic or Keyword label next to the result count so agents know which mode answered.
Search syntax
The usual search-engine shorthand works in both modes:
| You type | What it does |
|---|---|
frank invoice | Both words must appear somewhere in the conversation. |
"out of stock" | The exact phrase must appear. |
-refund or -"out of stock" | Conversations containing the word or phrase are left out. |
cart OR basket | Either word is enough. OR has to be in capitals. |
admin@example.com or example.com | An email address or domain is matched exactly. |
Search by meaning only adds conversations that are clearly about the same thing as the words you typed. Quoted phrases, addresses, and -exclusions still apply to those results, so a search for an email address never fills up with unrelated conversations.
Prerequisites
Before you start, make sure you have:
- FreeScout 1.8.101 or newer on PHP 8.1 or later.
- A working FreeScout queue worker and scheduler (
php artisan queue:workand theschedule:runcron). Indexing runs on them. - A Semantic Search licence from your ReplyRabbit account. The purchase email contains the licence key.
- Optional, for search by meaning: an API key from OpenAI or Google Gemini, or the base URL and model name of a compatible service such as OpenRouter, Ollama, or LM Studio.
Install the module
Download the ZIP
Log in at app.replyrabbit.app with the email address you used at checkout and open the Semantic Search card on the dashboard. Downloadsemantic-search.zip.Copy it into the Modules folder
Unzipsemantic-search.zipand copy theSemanticSearchfolder into theModulesdirectory of your FreeScout install, over SFTP or your host's file manager, next to the other modules. FreeScout has no in-app upload for third-party modules.Activate the module
Activate Semantic Search from the Modules list. Activation runs the database migrations that create the two index tables.Try a search
Search for a customer name plus a topic, for example a first name and "invoice". The results now match every word wherever it appears in a conversation, and the search page shows the Keyword label.
Keyword mode works at this point with no further setup. The steps below unlock search by meaning and the similar conversations panel.
Enter the licence key
Open the settings page
In FreeScout, go to Manage, then Settings, then Semantic Search.Paste the licence key
In the Licence section, paste the key from your purchase email and save. The status shows Licensed with the time of the last check.
The licence is tied to the site URL of the FreeScout install. If you move FreeScout to a new domain, contact hey@replyrabbit.app and we will reset it.
Set up search by meaning
Choose a provider
In the Embedding provider section, choose OpenAI, Google, or OpenAI-compatible. The default model is filled in for OpenAI and Google. For a compatible service, enter the base URL and the model name it expects.Add the key and test it
Paste the API key and click Test key. The test sends one short sentence to the provider and reports whether it answered. Keys are stored encrypted, and only a masked preview is shown after saving.Pick the mailboxes to index
In the Indexing section, tick the mailboxes to include. Include internal notes is on by default, because agents often search their own notes. Set Backfill days to how far back to index (the default is 365 days).Turn on search by meaning
Tick Search by meaning and save. If the provider, model, or base URL changed, the page tells you that conversations will be re-indexed in the background.Start the first index
Click Index now. The status block shows progress such as "Indexed 1,240 of 8,900 (14%)", the last run time, the last error if any, and the estimated remaining cost. Indexing runs in batches of about 200 conversations every five minutes, so a large desk takes a few hours. Search keeps working the whole time.
Which provider?
Keeping it up to date
When a new version is released, FreeScout shows it on Manage, then Modules, and Update Now installs it in place: no SFTP, no re-upload. The ZIP you downloaded from your dashboard carries your own licence's download link, so the update is fetched behind the same licence check as the first download.
Two things to know:
- The update only works for a copy downloaded from your dashboard, and you should not pass your copy on: its update link contains your own licence's download key, so anyone holding the ZIP could fetch updates on your licence. A copy from someone else is tied to their licence and updates on their key.
- If FreeScout reports a download error, download the new ZIP from your dashboard and replace the folder by hand, as in the install steps above. Your index and settings survive: they live in the database, not in the module folder.
Cost
Indexing sends the text of each conversation to your provider once, plus again if the conversation gets a new reply. Searching sends only the search words.
| Provider | Model | Price | About 100 conversations |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 0.02 USD per million tokens | roughly 0.01 USD |
| Google Gemini | gemini-embedding-001 | free tier, then per-token pricing | usually free |
| Ollama or LM Studio | any embedding model | none | none |
The settings page shows an estimate for the conversations still waiting to be indexed, so you can check the number before clicking Index now. Re-indexing only happens when you change the provider or model, or click Re-index everything.
Similar conversations panel
With search by meaning on, a Similar conversations panel appears in the conversation sidebar. It lists other conversations in the same mailbox that are about the same thing, with the subject, customer name, and date. Agents only see conversations they already have access to.
Turn the panel off for everyone with the Similar conversations toggle on the settings page. A new conversation shows "Nothing similar yet" until it has been indexed, which takes a few minutes.
Command line
Two commands help when you manage FreeScout over SSH:
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status prints the same coverage numbers as the settings page. reindex runs a batch straight away instead of waiting for the scheduler, which is useful for the first index on a large desk.
Troubleshooting
| Symptom | What to check |
|---|---|
| The search page shows Keyword instead of Semantic | Confirm Search by meaning is ticked, the licence status is Licensed, and the status block shows no recent error. If the key failed, search falls back to keyword mode until it is fixed. |
| No label shows on the search page at all | The search was handed to FreeScout's own search. This happens for searches that are only a number (ticket or order numbers), which core already handles well. |
| Test key fails | Check the key has no leading or trailing spaces and belongs to the right provider. For a compatible service, confirm the base URL is reachable from the FreeScout server and the model name is exactly what the service expects. |
| Status says "Nothing indexed yet" | Make sure the queue worker and scheduler cron are running. Click Index now and refresh after a minute. On shared hosting the first batch can take a few minutes to start. |
| Indexing stops partway | Read the last error on the status block. Rate limits and quota errors from the provider are the usual cause; indexing resumes on the next scheduled run. |
| Search results are slow on a very large desk | Keyword mode checks every search word against message text, which is heavier than core's single phrase match. Keep searches to a few words, or reduce the mailboxes included in indexing. |
| Similar conversations panel is empty | The conversation has not been indexed yet, or the panel is turned off in settings. New conversations are indexed within a few minutes. |
Privacy and data handling
Keyword search runs entirely inside your FreeScout database and sends nothing anywhere. With search by meaning on, the text of each indexed conversation (subject, customer messages, agent replies, and internal notes if included) is sent once to the provider you configured, over HTTPS, using your own key. Only the fingerprint comes back and is stored.
The only contact with replyrabbit.app is the licence check, which sends the licence key, the FreeScout site URL, and the module version. No conversation text, search words, or customer data are sent to us.
If conversation text must stay on your own servers, use Ollama or LM Studio as the provider, or stay in keyword mode.
FAQ
Do I need ReplyRabbit to use Semantic Search?
No. Semantic Search is a separate FreeScout module from the same makers. It installs and runs on its own. ReplyRabbit is only where you buy it, download it, and manage the licence key.
Does Semantic Search work without an AI key?
Yes. Keyword mode is on from the moment you activate the module, with no key and no settings. Every word in your search has to appear somewhere in the conversation, in the subject, customer name, email address, or message text. The AI key only adds search by meaning and the similar conversations panel.
Which AI providers can I use?
OpenAI (text-embedding-3-small by default), Google Gemini (gemini-embedding-001 by default), or any OpenAI-compatible service such as OpenRouter, Ollama, or LM Studio where you enter the base URL and model yourself. Z.AI is not supported because it has no embeddings service.
How much does the AI key cost?
With OpenAI text-embedding-3-small at 0.02 USD per million tokens, indexing about 100 conversations costs roughly 0.01 USD. A desk with 10,000 conversations pays around 1 USD to index everything once, then a few cents a month for new mail. The settings page shows an estimate before the first index runs.
Where is the search data stored?
In two tables inside your existing FreeScout database. Each indexed conversation adds about half a kilobyte. No separate search server is needed, and nothing is stored on replyrabbit.app.
Does it work on PostgreSQL?
Yes. Keyword search and search by meaning both work on MySQL, MariaDB, and PostgreSQL.
What happens if my key stops working or the licence lapses?
Search drops back to keyword mode on its own, so agents keep getting results. The settings page shows the reason. Keyword search never depends on the licence or the key.