---
lang: en
---

# Messenger

The Messenger is the chat widget a team puts on its own website, so visitors can ask questions there and be handed to the team. You add its script to your site from Connect › Install, choose which sites and pages it may load on, then style it in Connect › Appearance.

> Verified against the product on 2026-11-20

## Set up the Messenger

1. In [Connect › Install](https://app.heycactus.ai/deploy/messenger), use the **Set it up** card. Its prompt tells your coding agent to put the Messenger on every page and check that it loads.
2. To paste the script yourself instead, open **Paste the snippet yourself**, pick your framework, and select **Copy the snippet**.
3. Put the snippet where your framework says.

| Framework | Where the snippet goes |
| --- | --- |
| Script tag | In the shared root layout or footer template, just before the closing body tag, so it loads once on every page. |
| Webflow | In **Site settings**, **Custom code**, **Footer code**. |
| WordPress | In your theme’s footer, or in a header-and-footer code plugin. |
| React | Mounted once as a component in the root layout. |
| Svelte | In `src/app.html` for SvelteKit, or `index.html` for Vite, before the closing body tag. |
| Vue | In `index.html`, before the closing body tag. |
| Next.js | Saved as `app/cactus-messenger.tsx`, with `<CactusMessenger />` rendered once inside the root layout’s body. |

The script tag snippet is this, with your product’s public key in place of `<your public key>`. The key is shown on the Install screen, and the Messenger is not connected until the snippet runs on a page.

```html
<script>window.CactusMessenger=window.CactusMessenger||Object.assign(function(){(window.CactusMessenger.q=window.CactusMessenger.q||[]).push(arguments)},{q:[]});</script>
<script
  id="cactus-messenger-loader"
  src="https://messenger.heycactus.ai/v1/messenger.js"
  async
  data-cactus-messenger
  data-api-key="<your public key>"
></script>
```

> **Note:** The loader carries the id `cactus-messenger-loader`, so a second copy of the script is easy to spot.

The Install page lists each site the Messenger has loaded on under **Sites**, with the site’s address. A site shows there the first time the Messenger loads on it, and it reads **Running** or **Not seen today**.

### If the Messenger doesn’t load

To check a site before visitors reach it, open **Check a site** under **Only these sites can load it** and select **Check**. Cactus then checks that your install key works and that the site is on your list.

## Which sites can load it

Until you save a domain under **Only these sites can load it**, any site can load the Messenger. Once you save one or more, only those sites can load it.

To add a site, type it in **Add an allowed domain** and press `Enter`, or leave the field. Then select **Save**.

- A site is matched exactly, so `https://acme.co.uk` does not cover `https://www.acme.co.uk`. Cactus offers the other form after you add one.
- A `*` covers subdomains, so `https://*.acme.com` also covers `https://app.acme.com`.
- `localhost` is allowed over http only, on `127.0.0.1` too, at any port.
- Cactus’ own app is always allowed.

## Hide it on some pages

Under **Where it appears**, the **Hide on these pages** list holds the pages the Messenger does not show on. The section reads **On every page** until you add one, then **Hidden on 1 page** or **Hidden on** a count of pages.

- Pick a site in the **Site** box when you have more than one site. A pasted whole address on an allowed site fills in its own site.
- Select **Subpages** on a row to hide every page under that path too.
- A pasted address with a query or a `#` fragment is read as its path, and the row shows a note. A path after `#` covers every page of the app.
- A product can hide the Messenger on up to 50 pages.

Select **Save** after you change the list. Under **Check a page**, type a page address to see whether it shows the Messenger: **Shown on this page**, or **Hidden by** the rule that hides it.

A page that runs as one app, with steps that share one address, can hold the Messenger hidden from your own code. Call `CactusMessenger('visibility', 'hidden')` while the flow runs, and `CactusMessenger('visibility', 'auto')` when it is done.

## Change how it looks and what it says

Open [Connect › Appearance](https://app.heycactus.ai/deploy/messenger/appearance) to change the Messenger on a preview of your site before you save it.

| Setting | What it does |
| --- | --- |
| Default greeting | The words on the launcher. Empty shows “Ask me anything about” your product’s name. Up to 28 characters. |
| Suggested questions | Up to five questions the launcher turns through after its words, each up to 28 characters. Empty fields are dropped. |
| Color scheme | Auto, Light or Dark. |
| Position | Bottom left, Bottom center or Bottom right. |
| Eye color | One colour for light sites and one for dark sites. **Reset to brand** returns both to the brand. |
| Play sounds | Plays the open, close, send and receive sounds. |
| Show citations | Shows where an answer came from. |
| Show “Powered by Cactus” | Shows the credit line on the Messenger. |
| Remember past conversations | Keeps a visitor’s past conversations. |
| Tell people when an answer changes | Tells a visitor when an answer they saw has changed. |
| Cactus cursor | Shows Cactus’ cursor in place of the visitor’s own while the Messenger is open. Off until you switch it on. |
| Let AI browsers use Cactus | Lets an AI browser on your site use the Messenger’s tools. On unless you switch it off. |
| Debug logging | Logs Messenger events to the browser console. |

The logo is not set here. Select **Change in Settings**, which opens the logo under [Settings](https://app.heycactus.ai/settings/appearance). The Messenger’s own primary and secondary colours are set in Settings under Accent.

Select **Save** in the bar at the foot of the preview. While your changes are unsaved, the bar says that your site still shows the last saved design, and **Discard** puts the saved design back.

Once you save, Cactus translates the Messenger’s words for each language your help site has added. A product with no added language is not sent to translation. See [Translation](https://cactus.heycactus.ai/pkg3jf-translation) for the languages.

The preview runs on a live key when your key loads. If it doesn’t, it gives sample answers under **Demo key · sample answers**, and you should retry above it. Test chats from the live key show up in the Inbox.

## Know who the visitor is

Optionally, call `CactusMessenger('identify')` after your visitor logs in. The name labels the conversation, which stays on that browser.

Your server can sign each visitor’s ID, so their conversations follow them to a new device and onto your help site. Only a teamspace owner can create the signing secret, and only an owner can rotate it.

Select **Create signing secret** under **Logged-in visitors**. Cactus shows the secret once, and nothing shows it again, so copy it then.

Sign the visitor’s ID on your server with HMAC-SHA256, keyed with the secret, in hex. Cactus shows a sample in Node, Python and Ruby.

Then call the Messenger with the signature.

```js
// After your user signs in (optional).
// identityToken is HMAC-SHA256(userId) computed on your server. Without it the
// name still shows, but the conversation stays on this browser.
CactusMessenger('identify', {
  user: { userId: user.id, email: user.email, name: user.name },
  identityToken,
})
```

**Refuse unsigned visitors** turns away a visitor your server has not signed. Use it only on a site where everyone logs in. Cactus does not let it go on until a secret exists.

If your product’s secret comes from an environment variable, you set it there and Cactus does not create one on this screen.

To share what your app knows, call `CactusMessenger('context')` with a function or a snapshot. Cactus reads it fresh on each message and never uses it to grant access.

## If something is wrong

| What you see | What it means | What to do |
| --- | --- | --- |
| “isn’t on the list, so the Messenger is blocked there.” | The site you checked is not among your allowed sites. | Select **Add** with the site’s address, then **Save**. |
| “Save your domains first.” | You changed the allowed sites and have not saved them, so **Check** is off. | Select **Save**, then check again. |
| “Your install key isn’t answering: …” | Cactus could not reach your install key. | Check your connection and try again. |
| Unknown key | The key in the snippet is not one Cactus knows. | Copy the public key from the Install page again and replace the one in your snippet. |
| The site is not on your allowed list. | The site is not on your allowed list. | Add the site under **Only these sites can load it** and save. |
| “Couldn’t create your install key.” | Cactus could not create the key the snippet uses. | Select the retry the card offers. |
| “Save your pages first.” | You changed the hidden pages and have not saved them, so **Check a page** is off. | Select **Save**, then check again. |
| “Only a teamspace owner can change this.” | Only an owner can create or rotate the signing secret. | Ask an owner of the team to make the change. |
| “Create a signing secret first.” | **Refuse unsigned visitors** needs a secret to exist. | Select **Create signing secret** first. |
| “This product already has a signing secret.” | Create only works while no secret exists. | Select **Hold to rotate the secret** to replace it, which signs your users out of their history until your server uses the new secret. |

A visitor’s page shows no message when the key or the site is refused. The browser console shows the install error instead.

Conversations the assistant cannot answer are passed to the team: see [Handoffs](https://cactus.heycactus.ai/a5tamg-handoffs).


> **Note:** A visitor on a site you have not listed can still reach the Messenger until you save the first allowed site.
