Skip to content

Embedding the Chatbot Widget

HolderChat user guide

Documentation

Summary

You can add the HolderChat chat widget to a website in two official ways: a script embed and an iframe embed. Both use the same colour scheme and launcher button settings from Widget Appearance. Copy the snippet for the method you want, and paste it before the closing </body> tag on every page where the chat should appear.

WordPress Connector sites can show the widget automatically without a manual snippet. The plugin injects the script embed. On those sites you can still use a manual iframe snippet if you want isolation or custom CSS and JavaScript.

Prerequisites

  • Bot status Active
  • The API token (company token) for that bot, shown in the embed snippets under Widget Appearance and on Get Widget Code

The two embed methods

Script embed

This is the standard method. One script tag loads the widget onto the host page. It is simple to install and is the method the WordPress Connector injects for you.

Pros: one tag; the widget lives on the page itself, so a click outside the chat can close it; no extra frame.

Cons: HolderChat does not run your custom CSS or JavaScript on this path. Code like that would execute with access to your visitors’ page, which is not a safe default.

Script snippet:

<script src="https://holderchat.com/dynamic/get.js?token=YOUR_TOKEN" async></script>

Iframe embed

A small loader places the widget in a sandboxed iframe. The button and the open chat look the same as the script embed, including the launcher button builder settings.

The snippet is a script, not a bare <iframe> tag, because the loader has to resize the frame between the closed button and the open chat, and go full-screen on small screens. A static iframe tag cannot do that on its own.

The iframe is created with sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox" and without allow-same-origin. The document inside therefore gets an opaque origin. Custom CSS and JavaScript from Widget Appearance run only inside that frame. They cannot read the host page, and they cannot read holderchat.com cookies or a dashboard session.

Pros: isolation from the host page; optional custom CSS and JavaScript that stay inside the frame.

Cons: a click on the host page does not close the chat (use the close control in the widget); the conversation id is kept by the loader on the host page, because the sandboxed document cannot use cookies or storage of its own.

Iframe snippet:

<script src="https://holderchat.com/dynamic/iframe.js?token=YOUR_TOKEN" async></script>

Why custom JavaScript is iframe-only: on the script embed, that code would run on the host page. On the iframe embed, it runs in an opaque origin and cannot reach the parent document or HolderChat account cookies. Do not put secrets, API keys or passwords in the custom fields. Details are in Custom CSS and JavaScript (iframe only).

Step-by-step

  1. Open Dashboard and edit your bot, then open the Widget Appearance tab.
  2. Set the colour scheme and launcher button if you want, then save appearance.
  3. In Embed on your website, choose the Script or Iframe tab and copy the snippet. You can still copy the script tag from Get Widget Code if you prefer that screen.
  4. Paste the snippet before the closing </body> tag on every page where the chat should appear.
  5. If you chose the iframe embed and want custom CSS or JavaScript, add it in the same tab, save appearance, and test on your site. Those fields never apply to the script embed.

WordPress Connector (automatic script embed)

If you use the HolderChat Connector:

  1. WP Admin → HolderChat → Settings
  2. Enable Show chat widget on frontend
  3. Save — the plugin injects get.js (the script embed) automatically

A manual iframe snippet is optional if you want the isolated embed instead of, or in addition to, the plugin script. Use only one method on a given page so you do not load two widgets.

Verify installation

  1. Open your website in an incognito window
  2. The chat button should appear (usually in a bottom corner)
  3. Open the chat and send a test message
  4. If nothing appears, check the browser console, the bot status, and whether an ad blocker is hiding the widget

Cookies and session

The script embed sets cookies for session continuity:

holderchat_user_id — visitor identifier; holderchat_talk_id — conversation thread. Both last 48 hours.

The iframe embed cannot store those cookies inside the sandboxed document. The loader keeps the conversation identifiers in the host page’s localStorage and passes them into the frame so a returning visitor on the same browser can continue the thread.

What triggers a rebuild

Embedding does not trigger a rebuild. The token stays valid while the bot is Active.

Limitations

  • The token is tied to one bot — do not reuse it on another bot
  • The site must allow scripts from holderchat.com
  • CSP headers must allow holderchat.com scripts, and wss://holderchat.com for the chat WebSocket
  • Some ad blockers hide chat widgets
  • Custom CSS and JavaScript apply only to the iframe embed, never to the script embed or the host page

Troubleshooting

Symptom: Widget not visible

Cause: Script missing, wrong token, or bot not Active.

Fix: Verify snippet placement; check Active status; disable the ad blocker; confirm you did not paste both snippets on the same page.

Symptom: CORS or CSP errors

Cause: A strict Content-Security-Policy on your site.

Fix: Allow holderchat.com scripts and wss://holderchat.com WebSocket connections.

Symptom: Widget on the wrong bot

Cause: Wrong token in the snippet.

Fix: Copy the snippet again from the correct bot’s Widget Appearance or Get Code screen.

Related topics