Chat Widget — Viva Developer Docs

Quick Start

Add a fully featured AI chat assistant to your website in under 2 minutes. The widget streams real-time responses, handles bookings, and works on any site.

First, create your Viva account at goviva.ai/business-signup to get your Business ID and configure your AI persona in the dashboard.

Copy & Paste Installation

Add this snippet before the closing </body> tag:

<script>
(function() {
    window.viva = window.viva || function() {
        (window.viva.q = window.viva.q || []).push(arguments);
    };
    window.viva('init', { businessId: 'YOUR_BUSINESS_ID' });
    var s = document.createElement('script');
    s.src = 'https://goviva.ai/widget-v2/loader.js';
    s.async = true;
    document.head.appendChild(s);
})();
</script>

Replace YOUR_BUSINESS_ID with your Business ID from the Viva dashboard (Settings → Integrations).

That's it! A chat bubble will appear in the bottom-right corner. Click it to start a conversation.

How It Works

Queue & Load — The snippet creates a lightweight command queue, then asynchronously loads the widget loader.
Config Fetch — The loader calls your widget config endpoint to get theme, welcome message, and suggested actions.
Web Component — A <viva-chat> custom element is injected with full Shadow DOM isolation — no CSS conflicts with your site.
Streaming Chat — Messages are sent via Server-Sent Events (SSE) for real-time, token-by-token AI responses.

Embed Code

The embed code uses a queue pattern so you can call viva() commands before the script finishes loading. Commands are queued and replayed once the widget is ready.

Full Example

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <!-- Your content -->

    <!-- Viva Chat Widget -->
    <script>
    (function() {
        window.viva = window.viva || function() {
            (window.viva.q = window.viva.q || []).push(arguments);
        };
        window.viva('init', {
            businessId: 'YOUR_BUSINESS_ID',
            autoOpen: false,
            position: 'bottom-right'
        });
        var s = document.createElement('script');
        s.src = 'https://goviva.ai/widget-v2/loader.js';
        s.async = true;
        document.head.appendChild(s);
    })();
    </script>
</body>
</html>

WordPress

For WordPress sites, paste the embed code using one of these methods:

Theme footer — Go to Appearance → Theme Editor → footer.php and paste before </body>
Header/Footer plugin — Use a plugin like "Insert Headers and Footers" and add to the Footer section
Elementor — Drag an HTML widget and paste the embed code

Init Options

Pass these options to viva('init', { ... }):

Option	Type	Default	Description
`businessId`	string	—	Required. Your Viva Business ID
`autoOpen`	boolean	false	Automatically open the chat panel on page load
`position`	string	"bottom-right"	Widget position: `bottom-right` or `bottom-left`

Most configuration (theme, welcome message, suggested actions, logo) is managed in the Viva dashboard and fetched automatically at runtime. Client-side init options are intentionally minimal.

Server Config

The widget fetches its full configuration from the API on initialization:

GET https://api.goviva.ai/api/chat/widget/{businessId}/config

The response includes:

Field	Description
`widget.theme`	Preset theme name (purple, blue, green, red, orange)
`widget.primaryColor`	Custom hex color override
`widget.gradientColor`	Secondary color for gradients
`widget.welcomeMessage`	First message shown in the chat panel
`widget.quickReplies`	Suggested action pills shown below the welcome message
`widget.avatarUrl`	Avatar image for the assistant
`widget.position`	Default position (can be overridden by init options)
`widget.autoOpenDelay`	Milliseconds before auto-opening (if enabled)
`businessName`	Displayed in the chat header
`bookingSlug`	Enables booking features in chat (if set)

Preset Themes

Choose a preset theme in your Viva dashboard, or set a custom primaryColor. Available presets:

Theme	Primary	Dark
`purple`	#8B5CF6	#7C3AED
`blue`	#155DFC	#1447E6
`green`	#10B981	#059669
`red`	#E7000B	#C10007
`orange`	#F97316	#EA580C

Custom Colors

For full brand control, set primaryColor and optionally gradientColor in the Viva dashboard (Settings → Widget). These override any preset theme.

Position

The chat bubble can be placed in two positions:

Value	Description
`bottom-right`	Default. Chat bubble in the bottom-right corner.
`bottom-left`	Chat bubble in the bottom-left corner.

window.viva('init', {
    businessId: 'YOUR_BUSINESS_ID',
    position: 'bottom-left'
});

Greeting Bubble

The widget shows a proactive greeting bubble after a short delay (configurable via autoOpenDelay in the dashboard). This bubble appears next to the chat icon to encourage interaction, without fully opening the chat panel.

The greeting text uses your configured welcomeMessage. Users can dismiss it or click to open the full chat.

JavaScript API

Control the widget programmatically using the global viva() function:

// Open the chat panel
viva('open');

// Close the chat panel
viva('close');

// Toggle open/closed state
viva('toggle');

// Remove the widget from the page entirely
viva('destroy');

Custom Trigger Button

Use your own button to open the chat:

<button onclick="viva('open')">Chat with us</button>

Waiting for Ready

Commands called before the widget loads are automatically queued and replayed. No need to wait for a ready event.

// This works even before the loader finishes:
viva('init', { businessId: '4685' });
viva('open'); // queued, will fire once widget is ready

Identify Users

Pass user data to personalize the chat experience:

viva('identify', {
    name: 'Jane Doe',
    email: '[email protected]'
});

Call identify after init. You can call it at any time — for example, after a user logs in on your site.

Streaming Responses

The chat widget uses Server-Sent Events (SSE) to stream AI responses token-by-token. This gives users real-time feedback as the answer is generated, rather than waiting for the full response.

Streaming is enabled by default and requires no additional configuration.

Inline Actions

The AI can return clickable action links within chat messages. These are rendered as styled buttons that trigger specific behaviors:

Book appointment — Opens the booking flow inside the chat
Visit link — Opens a URL in a new tab
Contact — Opens email or phone link

Inline actions are configured on the server side through your AI persona setup. No client-side configuration needed.

Booking Slots

If your Viva account has a booking page configured (via bookingSlug), the AI can show available time slots directly within the chat panel. Users can select a slot and complete the booking without leaving the conversation.

Set up your booking page at business.goviva.ai → Calendar → Booking Page to enable this feature.

Troubleshooting

Widget Not Appearing

Check console for errors: Open DevTools (F12) → Console tab and look for [VivaChat] messages
Verify Business ID: Ensure it matches your Viva dashboard (Settings → Integrations)
Check for script conflicts: Ad blockers or CSP policies may block the widget
Clear cache: Try a hard refresh (Ctrl+Shift+R)

Chat Not Responding

Verify your AI persona is configured in the dashboard
Check that your knowledge base has content for the questions being asked
Look for network errors in DevTools → Network tab

Styling Conflicts

The widget uses Shadow DOM, so your site's CSS won't affect it and vice versa. If you see z-index issues, the widget uses z-index: 2147483647 (max value). Ensure no other elements use a higher stacking context.

Ad Blockers: Some ad blockers may block third-party widget scripts. If the chat doesn't appear for some users, this may be the cause.

Support

Email: [email protected]
Dashboard: business.goviva.ai