heycactus.ai

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

  1. 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.

  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

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 src/app.html for SvelteKit, or index.html for Vite, before the closing body tag.

Vue

Where the snippet goes

In index.html, before the closing body tag.

Next.js

Where the snippet goes

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>

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 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.

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.”

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.

Sources

Related pages