Skip to content
AskVault Docs
Try Free →

How to install the AskVault widget on any website

Written by Joseph Russo, Principal Architect, Networks and Tech, AskVault · Reviewed by Allison Chan
Last updated: 4 min read

What is the AskVault widget?

The AskVault widget is a JavaScript embed that puts an AI chat agent on any website. It loads asynchronously so it never blocks your page, runs on AskVault's infrastructure, and answers visitor questions from the content you trained it on. When that content does not cover a question, it says so instead of guessing.

Every response is sourced from documents you uploaded or sites you crawled, with clickable citations. Questions it can't answer show up in your knowledge-gaps list, and when the same one keeps recurring and auto-train is on, AskVault fires the knowledge.gap_detected webhook so you can backfill the content.

The widget works on every modern stack: WordPress, Shopify, React, Vue, Next.js, Angular, Svelte, plain HTML, Webflow, Wix, Squarespace. The same one-line snippet works everywhere because it's vanilla JavaScript.

Install the widget in 4 steps

Your agent answers from each page as soon as it's indexed. You need an AskVault account and access to your website's HTML.

1. Create a workspace and index your content

Sign up at askvault.co/signup on the Free plan, no credit card required. In the onboarding wizard, paste your website URL. AskVault finds your pages (from your sitemap, or by following links from your homepage when there's no sitemap), reads their text and indexes it privately for your workspace, up to your plan's content storage cap (5 MB on Free).

Crawl time depends on the size of your site and how quickly it responds. Your agent can answer from each page as soon as that page is indexed, so you can start testing before the whole site is done.

2. Open the Channels page and pick Widget

In the AskVault dashboard, click Channels in the left sidebar, then open the Web widget page. The embed snippet is shown there, with a live preview of how the widget will look.

Tweak the appearance now if you want: primary color, position (bottom-right or bottom-left), welcome message. Or accept the defaults and come back to it later in AI Agent > Appearance.

3. Copy the embed snippet

The generated snippet looks like this:

<script src="https://api.askvault.co/widget.js" data-token="YOUR_TOKEN" async></script>

The data-token attribute is unique per workspace. It tells the AskVault backend which knowledge base to answer from. The token is safe to keep public, it is not a secret, and rate limiting is enforced server-side per workspace.

4. Paste before the closing </body> tag

Paste the snippet right before </body> on every page where you want the widget. For most sites that's a single template file: your theme's footer.php (WordPress), _app.tsx or app/layout.tsx (Next.js), App.vue (Vue), index.html (plain HTML), or via Google Tag Manager.

Reload the site. The launcher button appears in the bottom-right corner. Click it. Ask a question. You'll get a grounded answer with clickable source links.

Verify it works

After deploying, test these three things to confirm the widget is healthy:

  1. The launcher loads on every page. Visit your homepage, a product page, and a blog post. The widget should appear on all three. If it doesn't appear on one, the script tag isn't on that page.
  2. Answers cite your content. Ask the agent something only your docs can answer. The response should include a "Sources" link to the relevant page. If sources are missing, indexing probably hasn't completed yet. Check the Knowledge progress bar.
  3. Conversations show up in the dashboard. Send a test message. Within 30 seconds it should appear in Inbox > Chat History. If it doesn't, the workspace token in the snippet is wrong.

Let visitors talk to a human

Turn on Let visitors talk to a human in Channels > Web widget and the widget shows a Talk to a human option. Those conversations go to your Help Desk inbox, and the AI can also hand a chat to your team with the escalate_to_human skill. Live chat is on the Growth plan and above. On lower plans the switch is locked and names the plan you need.

Today a new agent starts with this switch off. While it is off, the widget shows no handoff option and the AI offers a contact form instead.

If nobody on your team joins within 2 minutes of a visitor asking, the widget tells the visitor nobody is available and shows a short form so they can leave their contact details.

Customize the widget appearance

Open AI Agent > Appearance in the dashboard for the full customization surface:

  • Primary color. Hex picker; matches your brand.
  • Logo. Replaces the AskVault "AI" icon in the launcher.
  • Welcome message. The first thing visitors see when they open the chat.
  • Position. Bottom-right (default) or bottom-left.
  • Identity verification (HMAC). Tell the agent which signed-in customer it is talking to, and stop anyone from posing as another user. See identity verification.

All changes preview live before you publish, and published changes reach your site without editing the embed snippet.

Remove the "Powered by AskVault" badge

Widgets on the Free and Starter plans show a small "Powered by AskVault" footer link. Upgrade to Growth or higher to remove it with the branding toggle in AI Agent > Appearance.

Custom domain

The widget script always loads from api.askvault.co/widget.js. If you want a full-page chat on your own domain, such as help.yourcompany.com, use the hosted chat page with a custom domain.

How the widget loads (Core Web Vitals impact)

The snippet loads the widget with async, so it never blocks your page from rendering. The bundle is about 73 KB compressed, and it renders inside its own shadow DOM with a fixed-position launcher, so it does not shift your layout or restyle your page.

FAQ

How does the widget find my knowledge content?

The widget calls /api/widget/chat on every message. AskVault's backend looks up the workspace by token, searches your indexed content (meaning-based and keyword search together), and returns an answer grounded in the best-matching passages. The widget never has direct access to your content. It just renders the answer the API returns.

Does the widget work without JavaScript?

No. The widget is a JavaScript-only embed. For users with JavaScript disabled, link to your Hosted Page as a fallback. It's a full HTML chat interface that works without JS.

How many widgets can I run on one workspace?

One workspace = one widget. If you need different widgets for different sites or product lines, create separate workspaces. The Starter plan includes 2 workspaces; Growth includes 5; Business includes 15.

Can the widget collect leads?

Yes. Enable the collect_lead skill under Automation > Skills. When the agent detects buying signals it asks the visitor for their name, email, and (optionally) phone, then logs the lead to Contacts > Leads with the full conversation context. You can export leads to CSV on Growth and up, send them to your CRM with webhooks, or sync them to HubSpot on the plans that include it.

What happens when I hit my message quota?

When you hit your monthly cap (50 for Free, 2,000 for Starter, 6,000 for Growth, 15,000 for Business), new visitor messages get a polite "we're busy right now, try again later" reply. You're never silently double-charged. Upgrade under Billing to reset the cap immediately.

These guides cover platform-specific setup and advanced widget configuration.

Was this page helpful?