Widget Setup & Customization
Everything you need to embed, configure, and customize the Pravia chat widget on your website.
Quick Start Guide
<script src="https://pravia.dev/loader.js" data-bot-id="YOUR_BOT_ID"></script>Create a Bot
Sign up, create a bot, and add knowledge sources (documents, website, or text). The system processes them automatically.
Get the Snippet
Copy the JavaScript snippet from your bot dashboard settings.
Embed on Site
Paste the snippet before the closing </body> tag. The widget appears instantly.
Data Attributes Reference
| Attribute | Required | Default | Description |
|---|---|---|---|
| data-bot-id | Required | Your unique bot identifier. | |
| data-theme | Optional | auto | Widget theme: 'auto' (default), 'light', or 'dark'. 'auto' follows the user's system preference. |
| data-position | Optional | bottom-right | Widget position: 'bottom-right' (default) or 'bottom-left'. |
| data-primary-color | Optional | Primary color hex value (e.g. '#2563eb'). Overrides the dashboard setting. |
Full example:
<script
src="https://pravia.dev/loader.js"
data-bot-id="bot_abc123"
data-position="bottom-right"
data-theme="auto"
data-primary-color="#0055ff"
></script>JavaScript API Reference
Methods
| Method | Description |
|---|---|
| PraviaWidget.open() | Open the widget programmatically. |
| PraviaWidget.close() | Close the widget. |
| PraviaWidget.toggle() | Toggle the widget open/closed state. |
Events
| Event | Payload | Description |
|---|---|---|
| widget-ready | { botId } | Fired when the widget has loaded and is ready. |
| widget-open | {} | Fired when the widget opens. |
| widget-close | {} | Fired when the widget closes. |
| widget-messageCount | { count } | Fired when the message count updates. |
// Listen for widget events
document.addEventListener('widget-ready', () => {
console.log('Widget is ready');
});
document.addEventListener('widget-open', () => {
console.log('Widget opened');
});
document.addEventListener('widget-close', () => {
console.log('Widget closed');
});
document.addEventListener('widget-messageCount', (e) => {
console.log('Unread messages:', e.detail.count);
});// Programmatic control
// Open the widget
PraviaWidget.open();
// Close the widget
PraviaWidget.close();
// Toggle open/closed
PraviaWidget.toggle();postMessage Protocol Reference
Parent → Iframe
| Type | Payload | Description |
|---|---|---|
| open | {} | Opens the widget. |
| close | {} | Closes the widget. |
Iframe → Parent
| Type | Payload | Description |
|---|---|---|
| ready | { botId: string } | The widget has loaded and is ready to receive messages. |
| open | {} | The widget was opened. |
| close | {} | The widget was closed. |
| messageCount | { count: number } | The message count was updated. |
Security
Always validate the origin of incoming postMessage events in your event listener. The loader captures the iframe's origin on the first 'ready' message and only accepts messages from that origin. Never trust payload data without origin verification.
Example:
// Send message to iframe
const iframe = document.getElementById('pravia-chat');
iframe.contentWindow.postMessage(
{ type: 'open' },
'*'
);
// Listen for messages from iframe
window.addEventListener('message', (event) => {
// Always validate origin against the widget's origin!
const { type, ...data } = event.data;
switch (type) {
case 'ready':
console.log('Widget iframe ready');
break;
case 'open':
console.log('Widget opened');
break;
case 'close':
console.log('Widget closed');
break;
case 'messageCount':
console.log('Messages:', data.count);
break;
}
});White-Label & Branding
Custom Colors
Override all widget colors to match your brand identity — header, bubbles, buttons, and text.
Logo & Favicon
Replace the default bot avatar with your company logo. Set a custom favicon for the widget iframe.
Font Customization
Choose custom fonts for the chat interface. Supports Google Fonts and self-hosted typefaces.
Remove Branding
Remove the 'Powered by Pravia' label from the widget footer on Pro and Business plans.
Custom Greeting
Set a personalized greeting message and avatar that visitors see when they first open the widget.
Language Override
Force the widget interface to a specific language regardless of the visitor's browser settings.
Platform Guides
WordPress
Add a 'Custom HTML' widget in Appearance → Widgets or paste the code in your theme's footer.php before </body>.
Shopify
Add the widget code to your Shopify theme's theme.liquid file. Works with all store themes.
Webflow
Embed the widget using Webflow's embed element or add it globally via the site custom code settings.
Wix
Use the HTML iframe element in Wix or add the snippet via the site tracking tools in settings.
Squarespace
Add the widget code using the Code Injection feature in Squarespace's advanced settings panel.
Custom HTML
Paste the snippet before the closing </body> tag on any HTML page. No framework required.