How RAQS works, end to end

Step 1 — One script line and the embed

It all starts with a single <script> line you add to your site. The script loads asynchronously in the browser, doesn't weigh your page down, and mounts its own isolated UI (an orb or a 3D mascot) onto the page. The script carries the site key you defined in the dashboard; the backend uses that key to select the correct tenant and its knowledge base.

As the script loads, two things are verified: whether the request's origin is on your allowed-domains allowlist, and anti-abuse protection via Cloudflare Turnstile. This stops anyone from copying your key onto their own site. Once the UI is ready, the visitor can tap the orb or the browser can catch a wake word.

<script async src="https://raqs.ai/v1/raqs.js"
  data-raqs="YOUR_SITE_KEY"></script>

Step 2 — Wake word and the realtime audio channel

To start talking, the visitor taps the orb (or a 3D mascot); optionally, the browser's Web Speech API also listens for a wake word. The wake word runs entirely inside the browser, so no continuous audio stream is sent to the server — a session opens only when triggered. This matters for both privacy and latency.

Once a session opens, audio is carried over LiveKit, a low-latency realtime transport layer. LiveKit establishes a bidirectional WebRTC channel: audio from the visitor's microphone streams to the server, and the assistant's spoken reply streams back to the visitor. This two-way channel is what enables barge-in — when the visitor starts speaking mid-reply, the assistant stops and switches to listening.

Step 3 — Speech to text (Azure STT)

Audio reaching the realtime channel enters the first stop of the Pipecat-based voice pipeline and is transcribed by Azure Speech (STT — speech to text). Azure STT works in a streaming fashion: words start resolving before the visitor finishes their sentence, and natural pauses signal that the sentence is done. This greatly reduces the 'wait for the end of speech, then start processing' delay.

Turkish and English are supported; the spoken language is detected and the conversation continues in the same language. The resulting text is then used both to query the knowledge base and to pose the question to the language model in the next step.

Step 4 — Retrieving from your content with hybrid RAG

This step is the heart of RAQS and the answer to 'how does RAG work'. RAG (Retrieval-Augmented Generation) means finding the relevant parts of your content and handing them to the language model before it generates an answer. You prepare your knowledge base ahead of time: you crawl your site (sitemap + pages; a headless browser is used for JS-rendered SPA sites; content is cleanly extracted with trafilatura; robots.txt is respected; there's a per-plan page quota), or you paste plain text/FAQ, or you upload PDF, Word, TXT, MD and CSV files.

This content is split into meaningful chunks, embedded into vectors with Azure embeddings (text-embedding-3-small), and stored in pgvector. At question time, hybrid retrieval kicks in: a semantic vector search finds the chunks closest in meaning, while a Postgres full-text search (FTS) finds exact word/term matches. The two lists are fused with RRF (Reciprocal Rank Fusion), so neither 'same meaning, different words' content nor 'contains that exact term' content is missed. A similarity threshold filters out irrelevant chunks.

On e-commerce sites, the schema.org JSON-LD data on product pages (product name, brand, price, stock, category) is also extracted in a structured form. So questions like 'is X in stock, how much is it?' are answered with real product data rather than guessed from free text.

Step 5 — Generating the answer with Azure OpenAI

The retrieved relevant chunks are handed, together with the visitor's question, to the Azure OpenAI gpt-4o-mini model. The model is given a firm rule: answer only from the provided context; if it isn't there, don't make it up, say you don't know. This is the core reason RAQS doesn't hallucinate — the model doesn't speak freely; it's bounded by your content.

The answer is produced in a streaming fashion; as soon as the first words are ready it moves to the next step, so the visitor doesn't wait for the whole answer to finish. The assistant's tone, persona and name are reflected in the reply exactly as you set them in the dashboard.

Step 6 — Text to speech (TTS) and optional agent action

The generated text is converted to speech with Azure Speech (TTS — text to speech) and streamed back to the visitor over the same LiveKit channel. Because it's streamed, the assistant can start speaking before the entire answer is written — a critical point that reduces perceived latency.

On some turns the answer isn't just speech. RAQS 'sees' the page and can take agent actions: it guides the visitor to the right product or page, shows an item from a list, and triggers actions like add-to-cart. A safety layer is in place here: sensitive operations like payment, account changes or deletion always require the visitor's explicit confirmation — the assistant never does these on its own.

Latency, privacy and what happens each turn

A turn flows end to end like this: speak → realtime transport (LiveKit) → Azure STT → hybrid RAG retrieval (pgvector + FTS + RRF) → Azure OpenAI answer → Azure TTS → optional agent action. The fact that every stage is streaming is a deliberate design choice to lower total latency; the visitor hears each part of the answer start as soon as the previous part is ready.

Two principles matter for privacy. First, the assistant answers only from your knowledge base; when asked something not in your content, it says it doesn't know rather than inventing an answer. Second, the architecture is multi-tenant and data is isolated with row-level security (RLS) — one customer's content never leaks to another. The crawler is SSRF-guarded, the origin allowlist and Turnstile block abuse, hosting is in Azure's EU region, and the system is designed with KVKK and GDPR awareness.