# Spark Website Widget

{% hint style="info" %}
**Click** [**here**](https://discord.com/oauth2/authorize?client_id=1069423090225918082\&permissions=275146722545\&integration_type=0\&scope=applications.commands+bot\&redirect_uri=https%3A%2F%2Fcommunityone.io%2Fdashboard%2Fbot-auth-complete%2F%3Fsource%3Dgitbook\&response_type=code) **to introduce our bot to your server.**
{% endhint %}

## Website Widget

The Website Widget lets you embed your Spark AI agent as a chat bubble on any webpage. Visitors get instant, on-brand answers powered by the same knowledge base your Discord bot uses — no login required.

<figure><img src="https://3533212473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMmfBBh2ORXj35Ey5JhNd%2Fuploads%2FU2JQHFB6LsQrwoDYDWr1%2Fimage.png?alt=media&#x26;token=f177b0df-9517-4214-ad03-e5bcce898e5b" alt=""><figcaption></figcaption></figure>

### Prerequisites

The Website Widget is a Premium feature. Your server must have one of the following:

* Spark Premium
* Analytics (any level)
* Enterprise

If you don't see the Website Widget tab in your dashboard, you may need to upgrade your plan.

### Getting Started

{% embed url="<https://www.youtube.com/watch?v=fuaqrfzFBck>" %}

#### Step 1: Create a Widget

1. Go to your CommunityOne Dashboard → Spark → Website Widget tab.
2. Click + Add Widget.
3. A new widget is created in a disabled state. Click Edit to start configuring it.

<figure><img src="https://3533212473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMmfBBh2ORXj35Ey5JhNd%2Fuploads%2FsBwUv5ZNif8Pul3jZqDq%2Fimage.png?alt=media&#x26;token=d7afce00-f3ed-418e-8c30-07299bb2a75d" alt=""><figcaption></figcaption></figure>

#### Step 2: Enable the Widget

At the top of the editor, you'll see a master toggle. Flip it to On when you're ready for the widget to go live. While the toggle is off, the embed snippet will not load on your site even if you've pasted it. Remember to add the allowed domain before switching it on.&#x20;

<figure><img src="https://3533212473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMmfBBh2ORXj35Ey5JhNd%2Fuploads%2FYBVsDoeeMDzWq5coDy8c%2Fimage.png?alt=media&#x26;token=ad8310f7-77dd-436e-8b30-647814f8a2b4" alt=""><figcaption></figcaption></figure>

### Configuring the Agent

The Agent subtab controls what your widget says and how it behaves.

#### Widget Name

The display name shown in the chat header and in your widget list.

* Max length: 80 characters
* Example: `CommunityOne Support`, `Acme Help Desk`

<figure><img src="https://3533212473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMmfBBh2ORXj35Ey5JhNd%2Fuploads%2FPA7SkwG6mIlO85L5OEqS%2Fimage.png?alt=media&#x26;token=ea34071d-9d83-424d-913b-3c1557192df6" alt=""><figcaption></figcaption></figure>

#### Custom Prompt

Tell the agent who it is and how it should behave. This is the core instruction that shapes every response.

* Max length: 4,000 characters
* Example: *"You are a friendly support agent for Acme Inc. You help users with onboarding, billing, and feature questions. Always be concise and link to docs when possible."*

#### Conversation Style (Optional)

Fine-tune the agent's personality beyond the base prompt.

Style Tags — Pick up to 5 tags across four groups:

| Group   | Options                                       |
| ------- | --------------------------------------------- |
| Tone    | Friendly, Professional, Playful, Warm, Direct |
| Brevity | Concise, Detailed, Adaptive                   |
| Persona | Empathetic, Witty, Encouraging, Expert        |
| Voice   | First-person ("I"), Team ("we")               |

After selecting your tags, click Generate Style. We use what we already know about your community plus the tags you picked to write a complete style paragraph — no blank-page anxiety. You can edit the generated text freely.

Response Style Instructions — The generated (or manually written) paragraph that guides the agent's tone in every reply. This is separate from the custom prompt so you can iterate on personality without touching your core instructions.

<figure><img src="https://3533212473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMmfBBh2ORXj35Ey5JhNd%2Fuploads%2FoUa8Taws6msG1z0g1NKU%2Fimage.png?alt=media&#x26;token=207ae33a-6564-4b69-bdf4-d96362c9ab0c" alt=""><figcaption></figcaption></figure>

Limit Response Length — Control how verbose the bot is:

| Option            | Behavior                                                    |
| ----------------- | ----------------------------------------------------------- |
| Let the AI Decide | The agent picks an appropriate length based on the question |
| Conversational    | Keeps responses under 3 sentences                           |
| Casual            | Keeps responses under 5 sentences                           |

#### Starter Questions (Optional)

Configure up to 3 clickable suggestion chips that appear before the visitor sends their first message. These nudge users toward your highest-value conversation paths.

* Max length per question: 120 characters
* Examples: *"How do I get started?"*, *"What plans do you offer?"*, *"Can I see a demo?"*

Leave all three blank to hide the chips entirely.

<figure><img src="https://3533212473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMmfBBh2ORXj35Ey5JhNd%2Fuploads%2Fo7j8fZUH30J0vPWw6y1c%2Fimage.png?alt=media&#x26;token=360b3669-77ee-4695-863f-b80d018fd263" alt=""><figcaption></figcaption></figure>

#### AI Rules (Optional)

Natural-language "if this, then that" instructions that handle specific scenarios the base prompt doesn't cover. Write conditions and actions in plain English — no code, no flowchart builders.

Examples:

* *If the user asks for a discount* → *Offer them code WELCOME10*
* *If someone starts to bully you* → *Tell them this is a friendly community*
* *If they ask about pricing for teams* → *Point them to the contact form at /contact*
* *If the user asks something you don't know* → *Suggest they ask in our Discord server*

You can add as many rules as you need, reorder them, or delete any rule.

#### Disclaimer (Optional)

A small note displayed inside the chat window. Useful for legal or accuracy disclaimers.

* Max length: 1,000 characters
* Example: *"AI responses may be inaccurate. Please verify critical information."*
* Show only at start — Toggle this on (default) to display the disclaimer only at the beginning of the conversation. Toggle off to show it persistently.

<figure><img src="https://3533212473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMmfBBh2ORXj35Ey5JhNd%2Fuploads%2FRXS8tBWM8PXQMJwRjWNi%2Fimage.png?alt=media&#x26;token=fedcc393-a8b8-44c6-b474-8a07bf9ea348" alt=""><figcaption></figcaption></figure>

### Customizing the Style

The Style subtab controls the visual appearance of the widget. A live preview pane is shown next to the form so you can see every change in real time before saving.

#### Theme

Choose between Dark and Light mode for the chat window.

#### Primary Color

Your brand color, applied to the chat header, send button, and launcher bubble. Enter any hex value (e.g. `#7D19FF`) or use the color picker. Click the reset button to revert to the default.

#### Profile Picture

Upload a custom avatar that appears in the chat header and next to bot messages.

* Accepted formats: PNG, JPG, or SVG
* Max file size: 1 MB
* Click Remove to clear the avatar and fall back to the default icon.

#### Get Human Help

Sometimes the bot isn't the right answer. This adds a single "Get Human Help" button at the bottom of the chat that routes high-intent visitors to wherever your humans actually live.

Supported channels:

| Channel   | What to enter                    |
| --------- | -------------------------------- |
| Discord   | Your Discord invite link         |
| Instagram | Your Instagram profile URL       |
| Facebook  | Your Facebook page URL           |
| Telegram  | Your Telegram group/channel link |
| Discourse | Your Discourse forum URL         |
| Webpage   | Any URL (e.g. a contact page)    |
| Email     | An email address                 |

Select None to hide the button entirely.

<figure><img src="https://3533212473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMmfBBh2ORXj35Ey5JhNd%2Fuploads%2FlVGWsjnrIbxPBGyYf0AY%2Fimage.png?alt=media&#x26;token=9196739a-60c1-4931-ae54-0f24da47e8c9" alt=""><figcaption></figcaption></figure>

#### Bubble Alignment

Position the chat bubble on the Left or Right side of the screen. Default is right.

#### Launcher Icon

The icon inside the floating chat bubble. Choose from:

* Chat (speech bubble)
* Headset (support)
* Robot
* Sparkle
* Waving hand

#### Emoji Override

Paste any single emoji to override the icon entirely (e.g. 🚀, 👋, 🦊). This takes precedence over the icon selection above.

#### Launcher Background

| Option | Description                                                 |
| ------ | ----------------------------------------------------------- |
| Filled | Solid background in your primary color — maximum visibility |
| Subtle | Lighter, understated background                             |
| Bare   | No background — works best with an emoji or photo avatar    |

#### Launcher Animation

Add subtle motion to the launcher to grab attention:

| Option                 | Description                         |
| ---------------------- | ----------------------------------- |
| None                   | No animation                        |
| Wave once on page load | A one-time wave when the page loads |
| Gentle pulse           | A continuous soft pulse             |
| Occasional bounce      | Periodic bounce to catch the eye    |

#### Initial Message

The first message the bot sends when the chat is opened.

* Max length: 280 characters
* Example: *"Hey! How can I help you today?"*

<figure><img src="https://3533212473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMmfBBh2ORXj35Ey5JhNd%2Fuploads%2F9TEH1AXEa8nt5hudbQmt%2Fimage.png?alt=media&#x26;token=d83fd4a7-a5d0-4dbe-a4f9-0da3a8639e5c" alt=""><figcaption></figcaption></figure>

### Embedding on Your Website

The Embed subtab is where you configure allowed domains and grab the snippet.

#### Step 1: Add Allowed Origins

The widget will only load on domains you explicitly allow. This is a security requirement — requests from unlisted origins are rejected.

* Enter full origins including the scheme: `https://example.com`
* Each origin (scheme + host + port) must be listed separately
  * `https://example.com`
  * `https://www.example.com`
  * `http://localhost:8080` (for local development)
* Press Enter after each origin to add it as a chip
* Click Save allowed origins when done

> Note: Allowed origins are shared across all widgets on the same server.

#### Step 2: Copy the Embed Snippet

Once the widget is saved, a snippet is generated. Copy it and paste it just before the closing `</body>` tag of every page where you want the widget to appear.

\<script src="[https://cdn.communityone.io/widget/loader.js"data-widget-id="YOUR\\\_PUBLIC\\\_ID"async>\\](https://cdn.communityone.io/widget/loader.js"data-widget-id="YOUR\\_PUBLIC\\_ID"async>\\)</script>

The script loads asynchronously so it will not block your page render or affect page speed.

> Tip: If you use a CMS like WordPress, Webflow, or Squarespace, you can paste the snippet in the site-wide "custom code" or "footer injection" section so it loads on every page automatically.

#### Step 3: Save and Enable

1. Click Save Changes
2. Make sure the master toggle at the top is set to On
3. Visit your website — the chat bubble should appear in the corner you configured

### Security

The widget is designed for unauthenticated, public-facing use on customer websites. Multiple layers of protection are built in:

| Layer                     | What it does                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Origin allow-list         | Only requests from your listed domains are accepted. All others get a 403.                                                |
| CORS enforcement          | `Access-Control-Allow-Origin` is echoed only for validated origins.                                                       |
| Signed anonymous cookie   | Each visitor gets an HMAC-signed cookie (`cm1_widget_uid`) that lasts 1 year. No PII is stored.                           |
| Short-lived session token | A 1-hour HMAC token, bound to the specific widget + origin + user, is required for sending messages and fetching history. |
| Rate limiting             | Applied at three levels to prevent abuse:                                                                                 |

Rate limits:

| Scope                | Limit          |
| -------------------- | -------------- |
| Per user, per minute | 20 messages    |
| Per user, per day    | 200 messages   |
| Per IP, per minute   | 60 messages    |
| Per server, per day  | 5,000 messages |

### Saving and Unsaved Changes

A floating "Careful — you have unsaved changes!" bar appears at the bottom whenever you modify any setting. You can:

* Reset — Discard all changes and revert to the last saved state
* Save Changes — Persist your edits

Changes take effect immediately after saving — no redeploy needed.&#x20;

### Tips

* Start simple. Set a display name, write a short custom prompt, pick your brand color, and go live. You can always add style tags, AI rules, and starter questions later.
* Use starter questions strategically. Point visitors toward your most common or highest-value topics. This reduces "blank screen" drop-off and gets conversations started faster.
* Test locally first. Add `http://localhost:YOUR_PORT` to allowed origins during development so you can preview the widget before deploying.
* Keep an eye on the human-help fallback. If visitors consistently click "Get Human Help," that's a signal to improve your knowledge base or add more AI rules for those topics.

*For information on widget analytics, session tracking, content gap detection, and insights, see the Spark Analytics page.*

{% hint style="info" %}
Join [Discord](https://discord.gg/nVqt3z78Mw) for questions, comments, and a little gift <img src="https://fonts.gstatic.com/s/e/notoemoji/latest/1f381/512.gif" alt="🎁" data-size="line">  or back to [CommunityOne Home](https://communityone.io/)
{% endhint %}

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://communityone.gitbook.io/communityone/feature-deepdive/sparkai/spark-website-widget.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.