Home/Help Center/Chat widget setup

Channels

Install the Website Chat Widget

Create a chat widget, train it on your own knowledge, then copy two script tags into your site to add an AI chat panel with live handoff to your inbox.

By Chirag Darji · Updated 7 Nov 2026 · 7 min read

On this page
  1. Before you start
  2. Steps
  3. What you will see
  4. Settings and options
  5. Troubleshooting
  6. Related reading
Chat widget setup in VGraple CRM: appearance, welcome message, position and AI settings

Installing the chat widget means creating it under Settings, then Website, then Chat Widgets, filling in its Setup and Knowledge Base tabs, then copying two script tags from the Embed Code tab into your site just before the closing body tag; no other deployment step is needed on your side.

Chat widget setup: first 5 of 7 steps

  1. 1Go to Settings, then Website, then Chat
  2. 2Fill in the Setup tab
  3. 3Add the domain allow-list and bot disclosure
  4. 4Switch to the Knowledge Base tab and
  5. 5Configure lead capture, if you want it
The steps on this page, in order.

Before you start

  • Widget count is capped by plan: 1 on Free, 10 each on Starter and Growth, unlimited on Scale.
  • You need access to edit your website's HTML, or a platform (WordPress, Webflow, Shopify) with a custom code or tracking-scripts section.
  • The widget's AI is on Growth and above and uses AI credits: every workspace gets 1,000 free each month, and an AI reply costs 10.
  • Decide what you want the widget to know before you start: pricing, policies, FAQs, or documents, since a widget with no knowledge added will answer very little.

Steps

  1. Go to Settings, then Website, then Chat Widgets, and click New widget. Give it a Bot Name; this is an internal label, not shown to visitors when a Form Title is set.

Chat widgets list in VGraple CRM with the widget and the questions the AI could not answer

  1. Fill in the Setup tab. Set the Form Title, Header Subtitle, Welcome Message, Primary Color and Position under Widget Appearance. Under AI Settings, tick Enable AI Responses, choose an AI connection (Workspace default uses VGraple AI when you have no key of your own), and tick the Agent Actions you want the assistant to use: Capture leads, Request appointments, Answer from catalog, or Hand off to human.

  2. Add the domain allow-list and bot disclosure. Under Security, list the Allowed Domains the widget may run on (leave empty during testing), and under Safety & Handover set the Automated-experience notice plus Repeat the notice after for a returning visitor.

  3. Switch to the Knowledge Base tab and add content. Add an Article / Paste Text, an FAQ (Question + Answer), or a Website URL. Back on the Setup tab, tick Answer only from your knowledge under Safety & Handover if you want every answer strictly limited to what you have added.

  4. Configure lead capture, if you want it. Under Lead Capture, tick Show pre-chat form, choose which Form fields to show and require (name, email, phone with a Default country code picker covering more than 30 countries), and pick the pipeline under Add to Pipeline.

  5. Open the Embed Code tab and copy the script. It is two script tags: one that sets your widget's token, and one that loads the widget itself, both carrying your widget's unique embed token.

  6. Paste it into your site, just before the closing </body> tag. On WordPress this is usually a theme's footer script area or a code-insertion plugin; on Webflow and Shopify, a custom code or tracking-scripts section serves the same purpose. The launcher appears immediately once the page loads with the script present.

What you will see

A chat launcher appears in the position you chose (usually bottom-right) on every page where the script tag is present. Opening it loads the chat panel as a lazy iframe, so an unopened widget costs almost nothing on page load. Once a visitor has a conversation and it hands off, it appears in your shared team inbox tagged as a web chat conversation with the AI's transcript shown above the point a human took over.

Settings and options

Setting or fieldWhat it doesDefault
AI connectionWhich connected provider answers for this widgetWorkspace default: your default connection, or VGraple AI when you have none
Answer only from your knowledgeRestricts every answer about your business strictly to the widget's own knowledge baseOn (recommended); untick it to let the assistant also give general guidance about your field, said to be general, while still never guessing your prices, availability, timings or policies
Wait before replying (Instagram and Messenger)How long the assistant waits after a burst of Instagram or Messenger messages, so it answers them together4 seconds; the website widget needs no wait, because a visitor can send their next message once the reply has arrived
Allowed domainsUp to 20 domains the widget is permitted to load and message fromEmpty (unrestricted) until you add domains
Show pre-chat formShows a form for name, email and phone and creates a contact/lead on submitOff until turned on
Automated-experience notice and Repeat the notice afterThe message telling a visitor they are talking to an automated assistant, sent as its own message before the first answer on the website, Instagram and Messenger, and how often it repeatsSet per widget, repeats after 24 hours; required for compliance with Meta and general disclosure norms
Knowledge sharingWhether this widget's knowledge base is scoped to itself or shared with your other widgets and WhatsApp AI chatbotScoped to the widget unless you share it

Troubleshooting

SymptomLikely causeFix
Launcher does not appear on the siteThe script was pasted somewhere it never executes (inside a comment, a page builder's preview-only area) or the page has not been republished since adding itConfirm the script renders in the page's live HTML source, not just the editor, and republish the site if needed
Widget loads but the AI answers incorrectly or not at allNo knowledge has been added yet, or Answer only from your knowledge is on with content that does not cover the questionAdd or expand content on the Knowledge Base tab; untick Answer only from your knowledge if some general reasoning is acceptable
"This widget is not allowed on this domain" or similar blockThe allowed domains list has entries but the current site is not in itAdd the site's domain to the allow-list on the Setup tab
A visitor needed a person but the chat was never handed overThe visitor's wording did not match the hand-off detector, Hand off to human is not ticked, and your fallback message promises nobody, so the bot kept answering and offered a person insteadTick Hand off to human under Agent Actions so the AI can hand over on its own judgment, or word the fallback message to promise a person; a direct request like "talk to a person" always hands over, and a handed-over chat shows Needs a person in the inbox
Two widgets on the same page interfere with each otherEach widget is scoped by its own embed token, so this is unusual; check for a duplicated or mismatched script tagConfirm only the intended widget's script tag is present on that page

Feed the widget the same knowledge as your AI chatbot if you want consistent answers across WhatsApp and the website. See the inbox tour for how a handed-off web chat conversation appears, and escalating from AI to a human for how the handoff itself behaves.

Frequently asked questions

Does installing the widget require a developer?
No. You copy two script tags from the widget's Embed Code tab and paste them into your site just before the closing body tag. WordPress, Webflow, Shopify and plain HTML sites all have a place for this kind of custom code.
How many widgets can I create?
One on Free, up to ten each on Starter and Growth, and unlimited on Scale. Knowledge base, lead capture, branding and the domain allow-list ship the same at every tier, and the widget's AI is on Growth and above.
What does the AI actually answer from?
Whatever you add on the Knowledge Base tab, uploaded documents, pasted FAQs, or a URL. With Answer only from your knowledge ticked (the default), every answer about your business comes strictly from that content. Untick it and the assistant may also give general guidance about your field, saying it is general, but it still never guesses your prices, availability, timings or policies.
What happens when the AI cannot answer a question?
It has an explicit hand-off action it can call, and a visitor can also ask for a person directly. The conversation moves into your shared team inbox with the AI's transcript attached, so an agent has full context.
Can I restrict the widget to load only on my own site?
Yes. Add up to 20 allowed domains on the Setup tab and the widget's session and message endpoints reject requests from any other origin. Leave the list empty while testing and lock it down before launch.
Do web chat visitors become WhatsApp contacts automatically?
Only if they share a phone number, through the lead capture form or in conversation. That creates a contact your team can message on WhatsApp with consent; a visitor who never shares a number stays a web-only conversation.
Does the widget disclose that a visitor is talking to a bot?
Yes. You set the Automated-experience notice and how many hours pass before it repeats, under Safety & Handover on the Setup tab. It is sent as its own message before the assistant's first answer, on your website and on Instagram and Messenger, and again when a person hands the chat back to the assistant. Leave it empty to send none.

Run your WhatsApp on VGraple CRM

Free forever plan, official Meta WhatsApp Business API, set up in 15 minutes. No card needed.