Web chat

1. In Collabicle, open Apps › Channels, press Connect and choose A web chat. Give it a name and an address.
2. On its Install tab, add the sites the widget may appear on — https://your-site.com. www.your-site.com is a separate site; add both if you use both.
3. Turn the widget on and paste the line it shows before </body> on every page that should have the chat.
4. Switch the page Live.

<script src="https://collabicle.com/w/chat.js" data-chat="your-page" async></script>

The hosted page at collabicle.com/a/your-page works without any of this — share the link anywhere.

The script is small, loads after your page, and draws nothing at all if anything is wrong — your site never breaks because of it. The chat itself opens in a frame on the first click.

data-chat

The page’s address. Required. (data-agent, the old name, still works.)

data-position

left or right — overrides the side set on the Look tab.

data-launcher="none"

No button: open it yourself with window.collabicleChat.open(), .close() or .toggle() — from your own “Contact us” link, say.

data-base

Only for testing against another Collabicle origin.

Colour, greeting, suggested questions and the button’s label are set on the page’s Look tab, and change on your site without touching the line.

Open

Anyone. Most sites start here.

Email optional

Asks for an email first; the visitor may skip it.

Email required

No chat without an email. A typed email is a hint, never proof of who someone is.

Signed in on your site

Only visitors your server has signed in (below). On the hosted page, which cannot be signed, this shows a sign-in note.

Spam limits apply to everyone: messages per visitor per hour and open chats per visitor, set on the Visitors tab.

When a customer is signed in on your site, your server can tell Collabicle who they are. Your team then sees their name, email and company marked verified, nobody is asked for an email, and the same customer finds their conversation on any device.

Choose Signed in on your site on the page’s Visitors tab, reveal the signing secret there and keep it on your server. Then sign a token (a JWT, HS256) for each page render:

import jwt from "jsonwebtoken";

// On YOUR server — the secret never reaches the browser.
const token = jwt.sign(
  { email: user.email, sub: user.id, name: user.name, org: team.name, orgId: team.id },
  process.env.COLLABICLE_CHAT_SECRET,
  { algorithm: "HS256", expiresIn: "12h" },
);

import jwt, time, os  # PyJWT

token = jwt.encode(
    {"email": user.email, "sub": str(user.id), "name": user.name,
     "org": team.name, "orgId": str(team.id),
     "iat": int(time.time()), "exp": int(time.time()) + 12 * 3600},
    os.environ["COLLABICLE_CHAT_SECRET"],
    algorithm="HS256",
)

use Firebase\JWT\JWT; // firebase/php-jwt

$token = JWT::encode([
  'email' => $user->email, 'sub' => (string) $user->id, 'name' => $user->name,
  'org' => $team->name, 'orgId' => (string) $team->id,
  'iat' => time(), 'exp' => time() + 12 * 3600,
], getenv('COLLABICLE_CHAT_SECRET'), 'HS256');

Put it on the page before the script:

<script>
  // Before chat.js, on every page a signed-in customer sees.
  window.collabicleIdentity = {
    token: "<%= token %>",                       // from your server, per page render
    metadata: { plan: "pro", page: "billing" },  // optional, shown as unverified
  };
</script>
<script src="https://collabicle.com/w/chat.js" data-chat="your-page" async></script>

email

Required.

sub

Your user id — how the same person is recognised across devices.

name, org, orgId

Optional. Shown to your team.

iat

Required — the time it was signed. A token from the future is refused.

exp

Recommended. A conversation already started carries on after it expires; a new one needs a fresh token.

Anything wrong with a token — another secret, another algorithm, a missing email — and the visitor is treated as anonymous. The visitor is never shown why.

The metadata beside the token — the visitor’s plan, the page they are on — is passed to your team as written, marked unverified, because anyone can change what a page says. It never decides who may chat. Up to 8 entries, names up to 32 characters and values up to 120; anything longer is cut.

• The signing secret stays on your server. If it leaks, make a new one on the Visitors tab — every token signed with the old one stops working at once.
• Only HS256 is accepted.
• The browser refuses to show the chat on a site you have not listed, and the chat only takes a visitor’s signed-in details from a listed site.
• Where a visitor is (city and country) comes from our network, not from their browser. Conversations are deleted after the days set on the Visitors tab.

No chat button

Is the page Live, the widget on, and data-chat the page’s address? Open the browser console: the script stays silent, but a blocked request shows there.

“This chat isn’t available on this site”

The site is not on the Install tab’s list — exactly as the address bar shows it, https and www included.

Visitors see “Sign in to chat”

The page asks for signed-in visitors and no valid token arrived: check window.collabicleIdentity is set before the script, the secret is the current one, and iat is now.

Testing locally

Add http://localhost:3000 (your port) to the sites. Plain http is allowed for localhost only.