Widget Embed Guide

The widget is a Web Component (<web-chat-agent>) that loads asynchronously and runs on any site — no framework, no build step. The script renders a floating chat button; visitors click it to open the chat window.

Embed Code

Paste this right before the closing </body> tag:

<script src="https://app.webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
></web-chat-agent>

Replace YOUR_CHATBOT_ID with your Chatbot ID, found in Dashboard → Chatbot → Widget Customization, where the embed code is pre-filled with your ID. Copy it from there to avoid typos.

The widget calls the API on the same origin it was loaded from. Load the script from app.webchatagent.com and the chat requests go to app.webchatagent.com/api/... automatically — you never configure an API URL by hand.

How It Works

1. The async script loads in the background and does not block page rendering.
2. The <web-chat-agent> element renders a floating chat button.
3. The widget fetches your dashboard settings (colors, texts, tools, welcome message) and applies them. No extra attributes needed.
4. A visitor clicks the button, the chat window opens, and messages go to your AI chatbot.

HTML Attributes

Every visual setting from the Widget Customization page is applied automatically. HTML attributes on the element are optional overrides — use them only for per-page tweaks (e.g. a different position on one landing page). Attribute names are kebab-case (the widget maps theme-color to the themeColor prop internally).

Defaults below are the widget's built-in fallbacks. In practice most attributes are left unset and inherit the value you configured in the dashboard.

Basic Settings

Colors

All color attributes accept any valid CSS color (hex like #2563eb, rgb(), hsl()). When unset, the widget uses your dashboard value or its built-in fallback (the brand default is blue, #2563eb).

Images

Positioning

Content & Behavior

Prompt Buttons

Quick-action buttons rendered under the message list. Each button has a visible title and an action (the text sent as the user's message when clicked). Pass a JSON array as the attribute value:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  prompt-buttons='[{"title":"Talk to support","action":"I need help with my order"},{"title":"Pricing","action":"What does it cost?"}]'
></web-chat-agent>

Example: Full Customization

<script src="https://app.webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="abc-123-def"
  theme="modern"
  title="Support Chat"
  theme-color="#4f46e5"
  theme-text-color="#ffffff"
  user-message-color="#4f46e5"
  bubble-color="#4f46e5"
  font-family="Inter"
  initially-open="false"
  offset-x="30"
  offset-y="30"
></web-chat-agent>

Dashboard vs. HTML Attributes

Dashboard settings are stored server-side and loaded when the widget initializes. HTML attributes override them for that page only.

Recommendation: Do all visual customization in the dashboard. Reach for HTML attributes only when one page needs to differ — different positioning, a forced theme, or page-specific prompt buttons.

Custom CSS

For changes that go beyond the attributes above, target the widget's internal elements with your own CSS. Every styleable element carries a stable .wca-* class (for example .wca-header, .wca-message, .wca-bubble), so your selectors keep working across widget updates and don't need !important. You add the CSS in the dashboard, and it is injected into the widget's shadow DOM. See Custom CSS.

Inline Widget

To render the chat inside your page layout instead of as a floating button, use the inline variant. It loads a different script and a different element (<web-chat-agent-inline>):

<script src="https://app.webchatagent.com/widget/chat-widget-inline.js" async></script>
<web-chat-agent-inline chatbot-id="YOUR_CHATBOT_ID"></web-chat-agent-inline>

The inline element takes only chatbot-id; all other settings come from its own dashboard configuration. Place the element wherever you want the chat to appear, and size it with the surrounding container. See Inline Widget for details.

WordPress

On WordPress, use the official WebChatAgent WordPress Plugin instead of pasting the script manually. It handles the embed and updates for you. See WordPress Plugin.

Single Page Applications (SPA)

The widget works with React, Vue, Angular, and other SPAs out of the box. Add the script tag to index.html and place the <web-chat-agent> element in your app shell (e.g. the root layout). The widget persists across client-side route changes — you do not re-mount it on navigation.