WebChat Embedding

Overview

The Greentic WebChat widget can be embedded in your website in three ways, each suited to different use cases:

Embed Type	Best For	Integration Effort
Fullpage Link	Dedicated support pages, standalone chat portals	Minimal — just a link
Inline Iframe	Embedding chat in a specific area of a page	Low — one <iframe> tag
Chat Bubble	Persistent chat button on every page, customer support overlays	Medium — script tag + configuration

All three types are auto-generated as embed snippets when the greentic.cap.webchat.embed.v1 capability is enabled. You can find the generated snippets in assets/webchat-gui/embed/{tenant}.html after running the wizard or setup.

Fullpage Link

The simplest option. The WebChat provider serves a fullpage chat UI at a dedicated path. You just link to it.

<!-- Link to the fullpage WebChat -->
<a href="https://your-domain.com/webchat/gui/demo/default">
  Open Support Chat
</a>

The fullpage view uses the tenant’s skin files (colors, logo, title) from assets/webchat-gui/skins/{tenant}/fullpage/. You can customize index.html and page.css there.

提示

The fullpage link is useful for email signatures, QR codes, or any context where you want to send users directly to a chat session without embedding anything.

Inline Iframe

Embed the chat in a specific area of your page using an <iframe>. This gives you control over sizing and placement while keeping the chat isolated.

<!-- Inline iframe embedding -->
<iframe
  src="https://your-domain.com/webchat/gui/demo/default"
  width="400"
  height="600"
  style="border: 1px solid #e0e0e0; border-radius: 8px;"
  allow="microphone; camera"
  title="Support Chat"
></iframe>

Responsive Iframe

For responsive layouts, wrap the iframe in a container:

<div style="width: 100%; max-width: 480px; height: 70vh; min-height: 400px;">
  <iframe
    src="https://your-domain.com/webchat/gui/demo/default"
    style="width: 100%; height: 100%; border: none; border-radius: 8px;"
    allow="microphone; camera"
    title="Support Chat"
  ></iframe>
</div>

Chat Bubble

The chat bubble places a floating button on your page. When clicked, it opens a chat overlay. This is the most common choice for customer-facing websites where you want chat available on every page.

Basic Setup

<script>
  window.greenticChatConfig = {
    baseUrl: 'https://your-domain.com',
    tenant: 'demo',
    team: 'default'
  };
</script>
<script src="https://your-domain.com/v1/web/webchat/demo/embed.js" defer></script>

With Full Configuration

<script>
  window.greenticChatConfig = {
    baseUrl: 'https://your-domain.com',
    tenant: 'demo',
    team: 'default',

    // Appearance
    title: 'Acme Support',
    subtitle: 'We usually reply within minutes',
    logo: 'https://example.com/logo.png',
    primaryColor: '#E63946',
    backgroundColor: '#F1FAEE',
    position: 'bottom-right',
    offsetX: 20,
    offsetY: 20,
    bubbleSize: 60,
    bubbleIcon: 'chat',
    zIndex: 9999,

    // Behavior
    startOpen: false,
    greetingMessage: 'Hello! How can we help you today?',
    greetingDelay: 3000,
    showUnreadBadge: true,
    persistSession: true,

    // Size
    width: 400,
    height: 600,
    mobileFullscreen: true
  };
</script>
<script src="https://your-domain.com/v1/web/webchat/demo/embed.js" defer></script>

Configuration Reference

The window.greenticChatConfig object accepts the following options before the embed script loads:

Required Options

Option	Type	Description
baseUrl	string	Base URL of the Greentic runtime (e.g., https://your-domain.com)
tenant	string	Tenant identifier
team	string	Team identifier

Appearance Options

Option	Type	Default	Description
title	string	From skin.json	Chat window title displayed in the header
subtitle	string	undefined	Subtitle text below the title
logo	string	From skin.json	URL of the logo image shown in the header
primaryColor	string	From skin.json	Primary accent color (hex, e.g., #0078D4)
backgroundColor	string	#ffffff	Chat window background color
position	string	bottom-right	Bubble position: bottom-right or bottom-left
offsetX	number	20	Horizontal offset from the edge in pixels
offsetY	number	20	Vertical offset from the bottom in pixels
bubbleSize	number	60	Diameter of the floating bubble button in pixels
bubbleIcon	string	chat	Icon inside the bubble: chat, help, support, or a custom SVG URL
zIndex	number	9999	CSS z-index for the chat overlay and bubble

Behavior Options

Option	Type	Default	Description
startOpen	boolean	false	Open the chat window immediately on page load
greetingMessage	string	undefined	Proactive greeting shown in a tooltip above the bubble
greetingDelay	number	3000	Delay in milliseconds before showing the greeting
showUnreadBadge	boolean	true	Show unread message count badge on the bubble
persistSession	boolean	true	Persist chat session across page navigations using localStorage

Size Options

Option	Type	Default	Description
width	number	400	Width of the chat window in pixels
height	number	600	Height of the chat window in pixels
mobileFullscreen	boolean	true	Use fullscreen mode on mobile devices (viewport width < 768px)

Auto-Detection from Skin

When options like title, primaryColor, or logo are not explicitly provided in window.greenticChatConfig, the embed script automatically loads defaults from the tenant’s skin.json file. This means your chat bubble inherits your brand configuration without duplicating it in the embed code.

assets/webchat-gui/skins/demo/skin.json

{
  "title": "Acme Support",
  "logo": "/assets/webchat-gui/skins/demo/logo.png",
  "primaryColor": "#E63946",
  "backgroundColor": "#F1FAEE"
}

The resolution order is:

1. Explicit options in window.greenticChatConfig (highest priority)
2. Values from the tenant’s skin.json
3. Built-in defaults from the pack

Public JavaScript API

After initialization, the greenticChat object exposes methods to control the chat bubble programmatically:

// Open the chat window
greenticChat.open();

// Close the chat window
greenticChat.close();

// Toggle open/close
greenticChat.toggle();

// Check if the chat window is open
const isOpen = greenticChat.isOpen();

// Destroy the widget and clean up
greenticChat.destroy();

Example: Open Chat on Button Click

<button onclick="greenticChat.open()">
  Need help? Chat with us
</button>

Example: Open Chat After Delay

setTimeout(() => {
  if (!greenticChat.isOpen()) {
    greenticChat.open();
  }
}, 10000); // Open after 10 seconds

Example: Toggle from Custom Button

document.getElementById('my-chat-button').addEventListener('click', () => {
  greenticChat.toggle();
});

Mobile Responsive Behavior

The chat bubble adapts to mobile devices automatically:

• Viewport < 768px: When mobileFullscreen is true (default), the chat window opens in fullscreen mode, covering the entire viewport. A back/close button replaces the header close icon.
• Viewport >= 768px: The chat window opens as a floating panel next to the bubble, sized according to width and height.
• Orientation changes: The widget detects orientation changes and re-renders at the correct size.
• Touch interactions: The bubble button responds to touch events with appropriate hit targets (minimum 44x44px following accessibility guidelines).

Scaffold: Auto-Generated Embed Snippets

When the greentic.cap.webchat.embed.v1 capability is enabled, running gtc wizard or gtc setup generates ready-to-use embed snippets at:

assets/webchat-gui/embed/{tenant}.html

The generated file contains all three embed types with pre-filled configuration:

Fullpage Link

Fullpage link snippet

<!-- Fullpage Link -->
<a href="https://your-domain.com/webchat/gui/demo/default">
  Open Support Chat
</a>

Inline Iframe

Inline iframe snippet

<!-- Inline Iframe -->
<iframe
  src="https://your-domain.com/webchat/gui/demo/default"
  width="400"
  height="600"
  style="border: none; border-radius: 8px;"
  allow="microphone; camera"
  title="Support Chat"
></iframe>

Chat Bubble

Chat bubble snippet

<!-- Chat Bubble -->
<script>
  window.greenticChatConfig = {
    baseUrl: 'https://your-domain.com',
    tenant: 'demo',
    team: 'default'
  };
</script>
<script src="https://your-domain.com/v1/web/webchat/demo/embed.js" defer></script>

These snippets use the public_base_url from your provider configuration. If you use ngrok or Cloudflare Tunnel, gtc start replaces the URL automatically.

警告

The generated snippets are templates. In production, always set allowed_origins in your WebChat provider configuration to restrict which domains can embed the widget.

Next Steps

• WebChat Provider — full setup, OAuth, and features
• Bundle Assets — capability system and skin overlay
• gtc wizard — set capabilities in the answers file