Adding the IcloneU chat widget to your website lets visitors talk to your Clone without leaving your site. Pick your platform below and follow the steps to drop the widget in.
Each platform pastes the same snippet — a small script that contains your widget key. Copy that snippet before you begin: open API keys in the left sidebar, select your key, click Embed and use Copy script on the Web chat tab. Then follow the steps for your platform.
Add the widget to your site
Choose where the chat appears
The snippet usually goes in a site-wide header, so every page gets the same floating bubble. Three settings on the key change that page by page. Open API keys, select the key, click Settings and then Customize widget appearance; on the Web chat tab they sit in the Placement group. Click Done, then Save, and the change applies the next time a page loads.
- Display mode — Floating button is the usual bubble in a corner. Full screen fills the visitor's browser window with the chat itself: no bubble, no close button, and it opens by itself. The preview in that window always shows the floating layout, as the setting's hint says.
- Full-screen pages — shown once you pick Full screen. One path per line, such as /chat or /help/*, where * matches anything. Leave it empty and every page with the snippet gets the full-screen chat; list paths and only those pages do, while the rest keep the floating button.
- Hide on these pages — the widget doesn't load at all on these paths. Use it for checkout or cart pages, or for a page that has its own full-screen chat.
Paths are compared with the address of the page, ignoring capitals, the query string, anything after # and a final slash; a full URL pasted in counts by its path. /help matches that page only, and /help/* matches the pages under it but not /help itself, so list both if you want both.
Add <div data-icloneu-chat-page></div> to the page where the chat should go. The chat then sits inside that element instead of covering the window, so your header and footer stay visible. Leave the element without a height and the chat starts compact and grows with the conversation, up to most of the window, after which the messages scroll inside it; give it a height, such as style='height:600px', to hold a fixed block of the page instead. The page keeps scrolling normally, on phones too, and it only moves to the chat when the visitor asked for it, for example right after they sign in. Without the element the chat covers the whole window and the page behind it stays still.
Only one chat runs on a page. When a page carries the snippets of two keys (say, a site-wide sales chat and a course assistant pasted on one page), the page decides the same way on every load: a key hidden on that page steps aside, a key that is full screen on that page wins, and otherwise the first snippet in the page shows. So to give one page its own chat, set that chat to Full screen, or add the page to the other chat's Hide on these pages. If every key on the page hides it, the page has no chat. Snippets that a site-speed plugin delays or merges aren't recognized as snippets, and then whichever loads first wins.
Recognise your logged-in visitors
Out of the box the widget treats every visitor as a stranger. The snippet's commented-out window.IcloneUUser block lets your page say who the visitor is, and there is a whole tab for making that claim provable: open API keys in the sidebar, select the key, click Embed in the toolbar, and switch to the Identity tab. Its own summary is the shortest description of what this does: "Recognize your logged-in users in the chat. Your site tells the widget who the visitor is, and a signature (or your connected Shopify store) proves the claim - verified visitors get personalized answers, including their own order information."
There are three levels of claim, and only two of them are proof. The tab lays out the last two as Identity verification (the secret itself), Signed identity (any website) and Shopify storefront. A fourth group, Identified links, needs no claim at all: it is for links you send (below).
- Unsigned — the plain block, window.IcloneUUser = { userId: 'YOUR_USER_ID' }, optionally with an email, name and phone. It binds the conversation to a contact so history lines up under one person, and that is all it does. Anyone can type the same thing in their browser's console, so IcloneU treats it as a claim, not a fact: order questions still go through the one-time code.
- Signed — click Generate secret to give this key an identity secret. Your server computes an HMAC-SHA256 over userId + ':' + email.toLowerCase() + ':' + phone, hex-encoded, with absent fields as empty strings, and the page renders the result into the block as signature. The tab prints that formula above the snippet so your backend developer has it exactly. Note the phone is inside the signature on purpose: contacts are stitched together by email and phone, so a tamperable phone number on an otherwise signed claim could ride into another customer's purchase history.
- Shopify storefront — no secret and no backend. Paste the Liquid block from the same tab into theme.liquid in place of the plain snippet, and it sends the logged-in customer's Shopify id and email. IcloneU checks that pair against your connected store's admin API and, when it matches, throws the page's email and phone away and keeps the store's, so only store-attested contact details reach your contact list.
A proof earns the visitor the same 24-hour verified session the in-chat one-time code writes — nothing more and nothing less. Inside that window they can ask about their own orders without a code, and the store lookups are pointed at the verified email rather than whatever was typed in the chat. The tab states the same thing plainly: "Verified visitors are matched to your contacts and can ask about their own orders without an extra verification code. Visitors without a valid signature are still served normally - they just aren't treated as verified." Put an email in the signed block if you want that: the email is what an order lookup matches on.
For a site with no login at all. In a flow, a sequence step or a WhatsApp template button, put the Chat Identity Token variable, {{identity_token}}, on a link to a page with your chat, as its icu_id parameter: https://www.your-site.com/help?icu_id={{identity_token}}. On a WhatsApp template, the button's approved address ends in ?icu_id= and the variable fills in the rest. The variable is in the variable picker's Contact group. When the contact opens the link, the chat starts with the same verified session as a signed visitor, using the email and phone on their contact record, and the token disappears from the address bar so a copied link doesn't carry it. The tab shows an example under Identified links, and its warning is the rule to follow: "Each token works for 7 days and for anyone who has the link, so send these links only through the contact's own channel - never in a public post." An expired or altered link simply leaves the visitor anonymous.
A page can also ask the visitor who they are before the chat appears. The Student sign-in capture form, built under Automations on the Capture tab, asks for the email they bought with on Hotmart, checks the purchase and opens the chat as that buyer; until then the chat stays hidden. You paste its snippet from the Hotmart connection next to this chat's snippet. See Capture forms.
The tab's own warning is the rule: "Keep this secret on your server only - never in page JavaScript. Rotating or disabling it immediately invalidates signatures computed with the previous value." Anyone holding it can sign any identity they like, including your customers'. That is why only the account owner and team members whose role can manage Web Chat see the secret and the Generate secret, Copy secret, Rotate secret and Disable buttons; anyone else who opens the tab reads "Only members who can manage Web Chat can see or change the identity secret. Ask your account owner if you need it." Rotate secret replaces it in place — the widget key doesn't change and you don't re-paste the embed snippet, but every signature your backend computed with the old value stops verifying the moment you click it, so deploy the new value first. Disable switches signed identities off for this key entirely and the widget keeps working unsigned. None of this is how you rotate the hk- widget key itself — that is still delete-and-recreate, covered in Rotate or revoke a key.
Three limits are worth stating before you rely on it. A bad proof fails silently. A signature that doesn't verify — a stale secret after a rotation, a formula off by one character — is not rejected: the visitor is quietly demoted to unsigned and served as normal. That is deliberate, so a mistake never breaks your chat, but it does mean a broken integration looks exactly like a working one from the outside. The symptom to watch for is your logged-in customers being asked for a one-time code again. The signature does not expire. It proves the claim came from your server, not that it was made just now, so whoever can read a logged-in user's page can reuse it. There is no strict mode. Unsigned claims keep binding contacts as before; turning verification on for a key does not start refusing claims that lack it.
This one lives in the Embed dialog on the API keys page and is about proving who your visitor is. The Clone editor has its own Identity tab, which is about who your Clone is — its name, role and persona. They have nothing to do with each other.
Last updated October 29, 2026 · Platform connections
