# Install and customize Messenger

> Verified against the product on 2026-10-06

## Install Messenger

Get the generated snippet from **Connect › Messenger**. It includes your product’s public install key.

1. In **Connect › Messenger**, open **Or paste the snippet yourself**.
2. Choose your framework in **Framework**.
3. Select **Copy the snippet**.
4. Add the snippet once in the location for your framework.

| Framework | Where to add it |
| --- | --- |
| Script tag | Shared root layout or footer template, just before the closing body tag |
| Webflow | Site settings, Custom code, Footer code |
| WordPress | Your theme’s footer, or a header-and-footer code plugin |
| React | Mount it as a component once in the root layout |
| Svelte | `src/app.html` for SvelteKit or `index.html` for Vite, before the closing body tag |
| Vue | `index.html`, before the closing body tag |
| Next.js | Save it as `app/cactus-messenger.tsx` and render `<CactusMessenger />` once inside the root layout’s body |

> Keep the copied `data-api-key` as supplied, and don’t add a second copy of the loader to a page.

## Allowed sites

Until you save at least one allowed site, any site can load Messenger. After that, only sites on the saved list can load it.

1. In **Connect › Messenger**, open **Only these sites can load it**.
2. Enter the full site origin, including its scheme, in **Add an allowed domain**. For example, use `https://your-product.com`, not a bare host or a URL with a path.
3. Press Enter to add the origin to the list.
4. Select **Save** to apply the list.

If you use both a root domain and its `www` version, add both. The editor may offer the other version to add.

## Verify installation

**Check a site** tests whether the install key answers and whether the saved site list allows the origin. Save any domain edits first. The check doesn’t confirm that the snippet has loaded on your actual site.

1. In **Connect › Messenger**, open **Check a site**.
2. Enter the site in **Site to check**.
3. Select **Check**.
4. Load the page with the snippet in a browser. The site appears under **Sites** the first time Messenger loads there.

## Preview and customize

1. In **Connect › Appearance**, use **Preview site theme** to switch the simulated site’s background between **Light** and **Dark**.
2. Adjust the launcher, position, color scheme, and colors.
3. Select **Save** to apply the design to Messenger.

- detail: Reset every option to the Cactus defaults, Discard, Saved, Save
- detail: **Preview site theme** (1)

*In Connect › Appearance, use Preview site theme to switch the simulated site’s background between Light and Dark.*

Set primary and secondary colors separately for light and dark backgrounds. Unset colors use Cactus’s brand colors, and custom color values must be six-digit hex. The preview’s site theme changes the simulated background, not Messenger’s color scheme.

## Keep the launcher clear

Add `data-cactus-launcher-hold` to a host-page element, such as your hero section, to hold back a due launcher while that element is visible. The element must be drawn, have a size, and overlap the window. When no marked element remains visible, the launcher arrives with its usual entrance and stays on the page.

The hold is ignored on touch screens. It’s also bypassed when Messenger is open, a reply is waiting, or the launcher is otherwise needed immediately, such as when the dot is parked or being dragged.

## If a site check fails

| What you see | What it means | What to do |
| --- | --- | --- |
| The site URL isn’t valid | The entry isn’t a valid site URL | Enter a full URL, such as `https://your-product.com`, and check again |
| The site isn’t on the list | The saved site list blocks that origin | Select **Add [site URL]** to add and save it, then check again |
| The install key isn’t answering | The key check failed or Cactus couldn’t be reached | Check your connection and retry. Make sure the snippet’s `data-api-key` matches the public key under **Key** |
| The site doesn’t appear under **Sites** | Messenger hasn’t loaded on that site yet | Check that the snippet is installed and the site is allowed, then load the page in a browser |