Web Widget

The web widget adds a chat bubble to your website, allowing visitors to start conversations with your AI agent instantly.

Prerequisites

Before setting up the web widget:

• ✅ Chatwoot is connected (see Chatwoot Setup)
• ✅ Access to your website's HTML or CMS
• ✅ The main URL of the website where the widget will run

Setting Up the Widget

Step 1: Navigate to Channel Settings

1. Go to Integrations → Chatwoot tab
2. Find the Web Widget channel card
3. Click Configure or Connect

Step 2: Enter Widget Details

Field	Description	Example
Website Name	Name for this widget	"Main Website"
Website Domain	The main URL where the widget runs. Used as the widget's website URL and as the link target in proactive welcome emails.	https://example.com
Allowed Domains	(Optional) Additional domains where the widget is allowed to embed. Restricts which sites can load the widget. Leave blank to allow all domains.	https://example.com, https://www.example.com
Brand Name	Displayed in widget header	"Acme Realty"
Welcome Message	First message shown to visitors	"Hello! How can I help you today?"

Allowed Domains

Website Domain is the primary URL your widget runs on — this is required.

Allowed Domains is optional. When filled in, only the listed sites can load the widget, which prevents unauthorized embedding. Include all variations where the widget should work:

• https://example.com
• https://www.example.com
• https://staging.example.com (if testing)

Leave this field blank to allow all origins.

Step 3: Customize Appearance (Optional)

Option	Description
Widget Color	Primary color for the bubble and header
Position	Bottom-right or bottom-left
Launcher Icon	Custom icon or default chat bubble

Step 4: Save and Get Code

1. Click Save to create the widget
2. The code snippet appears automatically
3. Copy the snippet for installation

Installing the Widget

Option 1: Direct HTML

Add the snippet before the closing </body> tag. Always copy the snippet from PropPilot — don't reuse an older version, since recent updates enable automatic lead identification (see below).

Always copy the snippet directly from PropPilot — the snippet is regenerated each time you open the dialog and includes the latest identification logic. The exact code length and shape may change between updates; the only thing you need to do is replace the old script tag with the new one.

Option 2: Google Tag Manager

1. Create a new Custom HTML tag
2. Paste the widget code
3. Set trigger to All Pages
4. Publish the container

Option 3: WordPress

1. Install a plugin like "Insert Headers and Footers"
2. Paste the code in the footer section
3. Save changes

Option 4: Other Platforms

Platform	Method
Webflow	Project Settings → Custom Code → Footer
Squarespace	Settings → Advanced → Code Injection → Footer
Wix	Settings → Custom Code → Body - end
Shopify	Online Store → Themes → Edit Code → theme.liquid

Testing the Widget

After installation:

1. Visit your website in a browser
2. Look for the chat bubble (usually bottom-right)
3. Click to open the chat window
4. Send a test message
5. Verify the response appears in PropPilot inbox

Incognito Testing

Test in an incognito/private window to see the widget as a new visitor would.

Enabling Your Agent

To have your AI agent respond via the widget:

1. Go to Agents → Select your agent
2. Navigate to Channels tab
3. Enable the bot on Web Widget channel

Automatic Lead Identification

When a lead reaches your website by clicking the link in a proactive welcome email, the widget recognizes them automatically — they don't have to type their name or email again, and the AI agent already knows which property they were asking about.

This works because the email link includes a secure token in the URL. The widget script reads it on page load and identifies the visitor in the chat. If the visitor lands on your site any other way, the widget opens normally as an anonymous chat.

The widget always fetches the visitor's current name from PropPilot at identification time. So if the same lead chatted earlier on Telegram or WhatsApp and provided their full name, the website chat displays that updated name — never the stale value from when the email was sent.

Keeping the snippet up to date

If you copied the snippet some time ago, automatic identification may not work yet. PropPilot shows a Snippet outdated banner on the Copy Widget Script dialog when this is the case. To fix it:

1. Go to Integrations → Chatwoot → Web Widget
2. Click Copy Widget Script
3. Replace the current snippet on your website with the new one
4. Save and republish your site

If your widget was set up before this feature existed, you may need to disconnect and reconnect the Web Widget channel from PropPilot once, so identity validation gets enabled on the underlying inbox.

Customization Options

Welcome Messages

Set up automated greetings:

• Welcome Message: Shown when chat opens
• Away Message: Shown outside business hours (if configured)

Pre-Chat Form

Collect visitor information before chat:

• Name
• Email
• Phone number
• Custom fields

Configure in Chatwoot settings if needed.

Troubleshooting

Widget Not Appearing

1. Check domain authorization - Is your domain listed in Allowed Domains, or is that field left blank to allow all origins?
2. Check code placement - Is the snippet before </body>?
3. Check console errors - Open browser DevTools (F12) and look for errors
4. Clear cache - Try hard refresh (Ctrl+Shift+R)

Widget Appears But Doesn't Work

1. Verify Chatwoot connection status
2. Check webhook configuration
3. Review channel status in PropPilot

Styling Conflicts

If the widget looks wrong:

1. Check for CSS conflicts with your site
2. The widget uses an iframe, so most conflicts are rare
3. Contact support for custom styling needs

Best Practices

Do's

• ✅ Test on all domains where the widget is embedded
• ✅ Include mobile-responsive testing
• ✅ Set appropriate welcome messages
• ✅ Monitor conversations regularly
• ✅ Update Allowed Domains when adding new sites (if you use that restriction)

Don'ts

• ❌ Embed the widget on a domain you have blocked in Allowed Domains (it won't load)
• ❌ Use generic welcome messages
• ❌ Ignore the widget on mobile devices
• ❌ Forget to enable the AI agent

What's Next?

Set up additional channels:

• WhatsApp - Connect WhatsApp Business
• Telegram - Set up Telegram bot