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.
On this page
Set up the Messenger
In Connect › Install, use the Set it up card. Its prompt tells your coding agent to put the Messenger on every page and check that it loads.
To paste the script yourself instead, open Paste the snippet yourself, pick your framework, and select Copy the snippet.
Put the snippet where your framework says.
Framework | Where the snippet goes |
|---|---|
Script tag | Where the snippet goes In the shared root layout or footer template, just before the closing body tag, so it loads once on every page. |
Webflow | Where the snippet goes In Site settings, Custom code, Footer code. |
WordPress | Where the snippet goes In your theme’s footer, or in a header-and-footer code plugin. |
React | Where the snippet goes Mounted once as a component in the root layout. |
Svelte | Where the snippet goes In |
Vue | Where the snippet goes In |
Next.js | Where the snippet goes Saved as |
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.
<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>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.ukdoes not coverhttps://www.acme.co.uk. Cactus offers the other form after you add one. - A
*covers subdomains, sohttps://*.acme.comalso covershttps://app.acme.com. localhostis allowed over http only, on127.0.0.1too, 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 to change the Messenger on a preview of your site before you save it.
Setting | What it does |
|---|---|
Default greeting | What it does The words on the launcher. Empty shows “Ask me anything about” your product’s name. Up to 28 characters. |
Suggested questions | What it does Up to five questions the launcher turns through after its words, each up to 28 characters. Empty fields are dropped. |
Color scheme | What it does Auto, Light or Dark. |
Position | What it does Bottom left, Bottom center or Bottom right. |
Eye color | What it does One colour for light sites and one for dark sites. Reset to brand returns both to the brand. |
Play sounds | What it does Plays the open, close, send and receive sounds. |
Show citations | What it does Shows where an answer came from. |
Show “Powered by Cactus” | What it does Shows the credit line on the Messenger. |
Remember past conversations | What it does Keeps a visitor’s past conversations. |
Tell people when an answer changes | What it does Tells a visitor when an answer they saw has changed. |
Cactus cursor | What it does 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 | What it does Lets an AI browser on your site use the Messenger’s tools. On unless you switch it off. |
Debug logging | What it does Logs Messenger events to the browser console. |
The logo is not set here. Select Change in Settings, which opens the logo under Settings. 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 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.
// 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.” | What it means The site you checked is not among your allowed sites. | What to do Select Add with the site’s address, then Save. |
“Save your domains first.” | What it means You changed the allowed sites and have not saved them, so Check is off. | What to do Select Save, then check again. |
“Your install key isn’t answering: …” | What it means Cactus could not reach your install key. | What to do Check your connection and try again. |
Unknown key | What it means The key in the snippet is not one Cactus knows. | What to do Copy the public key from the Install page again and replace the one in your snippet. |
The site is not on your allowed list. | What it means The site is not on your allowed list. | What to do Add the site under Only these sites can load it and save. |
“Couldn’t create your install key.” | What it means Cactus could not create the key the snippet uses. | What to do Select the retry the card offers. |
“Save your pages first.” | What it means You changed the hidden pages and have not saved them, so Check a page is off. | What to do Select Save, then check again. |
“Only a teamspace owner can change this.” | What it means Only an owner can create or rotate the signing secret. | What to do Ask an owner of the team to make the change. |
“Create a signing secret first.” | What it means Refuse unsigned visitors needs a secret to exist. | What to do Select Create signing secret first. |
“This product already has a signing secret.” | What it means Create only works while no secret exists. | What to do 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.