RAQSSetup & Integration
RAQS setup: a voice assistant in one line of embed code
Adding RAQS to any website starts with a single <script> line. This guide walks through the six steps to take your voice assistant from zero to live: pasting the embed code, adding your site in the dashboard, building the knowledge base, setting allowed domains, picking a mascot with a persona/voice, and finally testing by talking. No code to write, no server to run, no AI infrastructure to manage — everything runs in the managed cloud.
Step 1 — Paste the one-line embed code on your site
Installation starts with a single script tag that runs on every page of your site. You paste this line into the <head> section (or just before the closing body tag). The data-raqs attribute is the unique key for your site in the dashboard; the script uses it to load the right knowledge base and settings. Because the tag is async, it doesn't slow your page load; the assistant prepares in the background and appears as an orb or 3D mascot once ready.
WordPress, Shopify, Wix, Webflow or your own hand-written HTML — it doesn't matter. You add the same line to any platform that has a 'custom code / header script' field in its theme editor. The beauty of a one-line install is that you can turn the assistant on and off without touching the rest of your site, and swap the key whenever you want.
Where it goes
In <head> or end of body so it runs on all pages.
Site key
data-raqs is the unique key from the dashboard.
async load
Doesn't affect page speed; prepares in background.
Platform-agnostic
WordPress, Shopify, Webflow, raw HTML — all of them.
<!-- RAQS voice assistant — one-line embed -->
<script async src="https://raqs.ai/v1/raqs.js"
data-raqs="YOUR_SITE_KEY"></script>Step 2 — Add your site in the dashboard and get its key
To get the YOUR_SITE_KEY value in the embed code, you log in to the dashboard and click 'Add site'. You enter the site's name and primary address (for example https://mystore.com); RAQS creates a record and a unique key for that site. When you paste this key into the embed line, the script knows which customer and which knowledge base it belongs to.
RAQS runs on a multi-tenant architecture: every site's data is completely isolated from the others with row-level security. So even if you manage multiple sites in the same dashboard, one site's knowledge base, conversations and settings never leak into another. In the dashboard you see a separate knowledge base, separate analytics and separate settings for each site.
Add site
Enter name + primary address; the key is generated.
Multi-tenant
Each site's data is isolated with RLS.
Single dashboard
Manage multiple sites from one place.
Step 3 — Build the knowledge base: crawl your site or upload content
RAQS never makes things up; it answers only from the knowledge base you give it, and if something isn't there it clearly says it doesn't know. That makes filling the knowledge base the most important step. The fastest path is the site crawl: you give the dashboard your site address and RAQS walks the sitemap and pages. JavaScript-rendered single-page apps (SPAs) are processed with a headless browser so they don't come back empty; text is extracted cleanly with trafilatura, stripped of menu/footer noise. The crawler respects robots.txt and is SSRF-guarded, and each plan has a page quota. You set the crawl depth in the dashboard and trigger a re-crawl whenever you want.
Alternatively, or in addition, you can paste content or upload files: PDF, Word, TXT, MD and CSV are supported, and you can enter frequently asked questions directly as text. Whichever method you choose, content is chunked, embedded with Azure embeddings (text-embedding-3-small) and stored in pgvector. On e-commerce sites, schema.org JSON-LD data on product pages (name, brand, price, stock, category) is extracted too — so when a visitor asks 'is this in stock, how much?' they get the right answer.
Site crawl
Sitemap + pages; headless render for SPAs.
Files & text
PDF, Word, TXT, MD, CSV or raw FAQ text.
Clean extraction
trafilatura strips menu/footer noise.
Product data
Price/stock/brand/category from JSON-LD.
Step 4 — Set the allowed domains (allowlist)
You want your assistant to run only on your site — not for someone who copies your key and uses it on their own. In the dashboard you define an allowed-domains list (origin allowlist): RAQS only accepts requests coming from these domains. This both limits usage to your sites and prevents abuse.
Alongside the allowlist, Cloudflare Turnstile anti-abuse protection is in place; this stops automated bots from misusing the assistant. The infrastructure is hosted in Azure's EU region and is KVKK- and GDPR-aware. While developing you can add addresses like localhost to the list, then leave just your production domain when you go live.
Origin allowlist
Assistant runs only on allowed domains.
Anti-abuse
Cloudflare Turnstile blocks bot misuse.
Dev + live
Manage localhost and production domains separately.
Step 5 — Pick the mascot, persona, voice and name
You choose your assistant's look and character with one click in the dashboard. You can use the classic tap-to-talk orb, or pick a 3D mascot that roams the page: the flagship deer, the universal 'Spark', stylized characters, and one from a pool of 30+ animals. The mascot treats the page's real DOM elements as terrain; it runs, jumps and guides the visitor to the right section.
Alongside the character, you set the voice, tone and name. The assistant speaks Turkish and English; STT/TTS runs on Azure Speech, while the brain runs on Azure OpenAI gpt-4o-mini through a Pipecat pipeline. The persona setting makes the assistant speak in your brand's voice — formal or casual, brief or detailed, and which name it greets people with; it's all up to you.
Mascot pool
Orb, deer, Spark, characters + 30+ animals.
DOM terrain
The mascot roams the page elements and guides.
Voice & persona
Turkish/English; tone, name and style configurable.
Step 6 — Test by talking and go live
The last step is the most fun: go to your site, tap the orb or mascot, allow the microphone and speak. Ask real questions like 'is this in stock?', 'what is your return policy?' or 'take me to the contact page'. The assistant finds the answer in the knowledge base with hybrid search (semantic vector + Postgres full-text keyword + RRF fusion + a similarity threshold), replies by voice, and when needed guides you to the right page or triggers actions like 'show me this' and 'add to cart'.
For sensitive operations like payment, account or delete, the assistant always asks for explicit user confirmation — this safety layer is on by default. During testing, you add any missing answers to the knowledge base from the dashboard or run a re-crawl. By reviewing conversations and analytics in the dashboard you improve the assistant over time. When you're ready there's nothing else to do: because the embed line is already live, the assistant is available to all your visitors.
Try real questions
Stock, returns, guidance — test by voice.
Confirm shield
Payment/account/delete need user consent.
Improve
Review conversations, add missing content to the KB.
FAQ
How do I add the voice assistant to my site?
Paste a single <script> line into your site's <head>, add your site in the dashboard, and put its key in the embed code. Then crawl the knowledge base and you're live in minutes.
Do I need to know how to code to set it up?
No. Copy-pasting the one-line embed is enough; everything else (adding the site, crawling, picking a mascot) is done by clicking in the dashboard.
How long does setup take?
The embed line takes seconds. Crawling can take a little time depending on your site's size, but a typical site is answering questions within minutes.
How do I update the knowledge base?
From the dashboard you can trigger a re-crawl anytime, upload new files or add text. Changes are processed into the knowledge base and the assistant answers with the latest content.
Does the assistant run only on my site?
Yes. Thanks to the allowed-domains list (origin allowlist) and Cloudflare Turnstile, the assistant runs only on the domains you specify; no one else can use your key.
Ready to start your setup?
Add your site with one line of code, crawl your content and start talking in minutes.
Start free