Live chat: install the widget on your site

The chat widget is a single script tag. What makes it slightly more than that is the domain allow-list: the widget checks which site it is running on before it renders.

That check is a security feature and the most common reason a correctly installed widget does not appear.

Who this is for

Whoever can edit your website's HTML, working with a KudosCRM admin.

Before you start

• Admin access to conversation settings in KudosCRM, to get the widget key and manage the allow-list.
• The ability to add a script tag to your site.
• The exact domains you will run it on — including staging, if you want it there.

Allow-list the domain first, or nothing renders
The widget asks the API whether it is allowed to run on the current origin. If the domain is not on the allow-list, that request is refused and no launcher appears at all — it fails silently rather than showing an error on your page. So add every domain you intend to run on, including staging and any alternate hostname, before you go looking for bugs in your installation.

Install it

1. Get your widget key
   Find it in conversation settings. The key identifies your workspace to the widget and is safe to have in your page source.
2. Allow-list your domains
   Add every domain the widget will run on. Do this before installing rather than after, so your first test is a fair one.
3. Add the script to your site
   Drop the loader script onto the pages where you want chat. Site-wide is usual; put it in your shared layout or template.
4. Load a page and look for the launcher
   The launcher should appear in the corner. If it does not, the allow-list is the first thing to check, not the script.
5. Send a test message
   Start a conversation from your own site and confirm it reaches the console. That closes the loop end to end.
6. Repeat for staging
   Staging is a different origin and needs allow-listing separately. Doing it now saves confusion later.

What you get

• Live chat on your site from a single script tag.
• A domain allow-list, so your key cannot be lifted and used on someone else's site.
• Conversations landing in the console where your team works.
• A tested install rather than a hopeful one.

Frequently asked questions

I added the script and nothing appears. What is wrong?

Almost always the domain is not allow-listed. The widget checks its origin before rendering and fails silently when it is refused, so there is no error on your page to find.

Is it safe to have the widget key in my page source?

Yes. The key identifies the workspace and only works from domains you have allow-listed, which is what the allow-list is for.

Do I need a separate key for staging?

No, the same key works — but the staging domain has to be allow-listed separately, because it is a different origin.

Can I put chat on only some pages?

Yes. The widget appears where the script is, so include it only on the pages or templates you want it on.