---
lang: en
---

# Messenger

The messenger is the chat box Cactus puts on your own website, so visitors can ask about your product where they are. You set it up in the web app, list the sites it may run on, and choose how it looks.

> Verified against the product on 2026-11-15

## Set it up on your site

1. Sign in to [The web app](https://app.heycactus.ai), and open [Messenger](https://app.heycactus.ai/deploy/messenger).
2. In the **Set it up** card, select the button that opens your coding agent. The agent puts the messenger on every page and checks that it works.
3. Or open **Paste the snippet yourself**, choose a framework, and copy the snippet. For **Script tag**, put it in the shared root layout or footer template, just before the closing body tag, so it loads once on every page.
4. Wait for the first visit. The site appears under **Sites** the first time the messenger loads on it, and the set-up card goes away.

## See which sites run it

Each row under **Sites** shows one site and whether the messenger has loaded there lately.

- **Live on** the site's address: the messenger loaded there in the last 24 hours.
- **Not seen today**: the messenger has not loaded there in the last 24 hours.

To add another site, select **Add another site** under the list. The set-up card comes back above it.

## Only these sites can load it

Until you save a site, any site can load the messenger. Once you save one, only the sites on the list can.

1. In **Only these sites can load it**, type a site's address and press `Enter` or `,`. An address without `https://` is saved with it added.
2. Select **Save**. The button reads **Saved** once the list matches what is saved.

> **Note:** Each address must match a visitor's site exactly. When the other form of your address, with or without `www.`, is offered under the list, add it too, because visitors on both need both.

### Check a site

1. Open **Check a site**, type the address, and select **Check**. The check looks at the saved list only, so save your domains first.
2. Read the result under the field.
   - Your key answers from the site and the messenger will load and chat there.
   - The site isn't on the list, so the messenger is blocked there. Select **Add** with the address to add it and save.
   - The address isn't a valid site URL.

## Signed-in users

**Signed-in users** stays off until a signing secret is created, and only a teamspace owner can create it. Until then, guests ask with no setup.

1. In **Signed-in users**, select **Create signing secret**.
2. Copy the secret that appears. It is shown once, and no later read gives it back.
3. On your server, sign each user's id with the secret, and pass the result to the messenger's identify call. The section shows the code for both.

> **Note:** To replace the secret, hold **Hold to rotate the secret**. Users stay signed out of their history until your server signs with the new secret.

### Refuse users who are not signed

The **Refuse users who are not signed** switch can be turned on only once a signing secret exists.

Off, guests can ask as well. On, a caller without a valid signature is turned away, so use it only on a site where everyone is signed in.

## Appearance

Open [Appearance](https://app.heycactus.ai/deploy/messenger/appearance) to change how the messenger looks. The preview shows it on a simulated site, and **Light** or **Dark** above it sets that site's background.

- **Name** is the name the messenger says in its words, such as its intro and the launcher's ask. It is the product's name until you type another in the **Name** field, which sits beside the launcher.
- The closed button can be the lit character, a drawn mark, a chat bubble, your own picture, or a frosted glass pill that says its words.
- It sits in a bottom corner, or at the foot of the middle for the glass pill.
- The chat bubble takes your brand colour, or two colours you pick.
- An intro says hello once a session, a moment after the button arrives, and is on unless turned off. While the intro would cover a part of the page marked with `data-cactus-keep-clear`, it waits, and says hello once that part is clear of it.
- Sounds, citations and Cactus's cursor can each be switched; Cactus's cursor is off unless turned on.
- The greeting, placeholder, button label and intro message are your words, translated for each help center language.

The messenger's own primary and secondary colours are set under Accent in [Settings](https://cactus.heycactus.ai/settings), not on this page.

## Talk to a human

**Talk to a human** is on by default exactly when the team has somewhere for a handoff to land, such as a Slack channel, a Discord channel or a saved escalation email. A choice the owner has stored overrides that default.

What happens to the question after that is told on [Handoffs](https://cactus.heycactus.ai/handoffs).

- A visitor who is not signed in can ask for a person 5 times an hour from one connection.
- The whole site can ask for a person 20 times an hour.
- A thread holds one place for an hour, so every press on it in that hour uses that one place.

## Visitor limits

A visitor who is not signed in can send 30 questions an hour on your site.

Past that, the messenger asks the visitor to slow down. The count frees up as the hour's earlier questions age out.

## If the messenger doesn't load

| What you see | What it means | What to do |
| --- | --- | --- |
| "This messenger is not set up for this site yet. Check the install key and allowed domain." | Your site is not on the list, or the install key is wrong | Add the site under **Only these sites can load it** and select **Save** |
| "The messenger API endpoint was not found. Check the script/API URL for this install." | The address the script loads from was not found | Copy the snippet again from **Set it up** and put it on the page |
| "Add your site to “Only these sites can load it” first. Without it the messenger loads unstyled and chat is blocked." | The list has sites, and yours is not one of them | Add your site and select **Save** |
| "Cactus couldn’t create your install key." | The product has no install key, so **Set it up** cannot run | Reload the page and try again |
| "Upload a picture for a light ground before choosing Your own image." | You chose your own launcher picture before uploading a light one | Upload a light picture, then choose Your own image |
| "Too many requests to reach the team right now. Try again later." | Too many requests to reach a person came in, so the handoff was refused | Try again later |
| "Cactus had trouble answering. Please try again in a moment." | Cactus's server did not answer | Try again in a moment |