How can we help?

Articles in this section

See more

Configuring the Web Widget for CloudRadial Chat

Ricky Cecchini
  • Updated

The Web Widget is the simplest Client Channel to deploy for CloudRadial Chat. You paste a snippet into your website's HTML, and end users get a floating chat bubble in the corner of the page. Clicking it opens a chat window where they can interact with your Dialog or ChatAI Responder.

End users on the web widget are anonymous by default - the Dialog will ask for their name and email as part of the conversation. 

If your site already knows who the user is (behind a login, for example), you can pass their identity to the widget so the Dialog can skip those questions and look them up in your PSA automatically.

Prerequisites

  • A CloudRadial Chat account with admin access
  • A web channel created in the admin portal
  • A PSA connector configured
  • HTTPS on the site where you'll embed the widget (self-signed certificates are not supported)

Getting Your Embed Snippet

When you first run through the setup of CloudRadial Chat, you will have the option to choose the web widget as a client channel. If you didn't set it up during the onboarding wizard, you can still set it up at any time (if you have a spare channel available) within the Chat Admin Console. To do so:

  1. Navigate to Channels in the sidebar.
  2. Select your web channel (or create one if you haven't yet via the +Add New Client Channel button).
  3. Enter in your details and channel preferences
  4. Copy the embed code from the Deployment Code banner at the top of the Channel Deployment section.

The snippet includes a CSS link, a JavaScript file, and a custom HTML element with your channel ID.

Adding It to Your Site

To add the chat widget, you'll need admin access to your site to enter into an editing mode where you can place an embedded code.

  1. Paste the snippet into your website's HTML, just before the closing </body> tag.
  2. Replace YOUR_CHANNEL_ID with the channel ID from the admin portal (this is already filled in if you copied from the Deployment Code banner).
  3. Save and publish your page.

You should see a chat bubble appear in the bottom-right corner of your page. Click it to test the conversation.

Configuration Options

Customizing the Widget (Advanced)

For most sites, you don't need to change anything: paste the snippet exactly as copied, and the widget works with sensible defaults, a floating chat bubble that starts a conversation when a visitor opens it.

If you do want to adjust its behavior, the snippet includes a small options setting (the part that looks like options='{"isOpen":"false", "autoStart":"true"}'). The two values there are:

  • isOpen (default: false) — set this to true to have the chat window already open when the page loads, instead of waiting for a click.
  • autoStart (default: true) — whether the bot greets the visitor and starts the conversation automatically when the chat opens.

There is also an authRequired option, which requires a visitor to sign in before chatting. This is mainly used for the CloudRadial UCP widget and matches the Authentication Required toggle on the channel's General tab. Leave it off for a public website widget.

Display Modes (Advanced)

By default, the widget is a floating bubble in the corner. Two other display styles are available if you'd rather present chat differently:

  • Mobile — a full-screen chat experience, good for a dedicated mobile support page.
  • Embedded — an inline chat with no bubble that's always visible, for placing chat directly into a page's layout.

Switching display modes, or hiding the bubble so you can launch chat from your own button, is a small code change best handled by whoever manages your website.

Theming

Colors, the bot avatar, and the bot name come from your channel settings, not the snippet, so you don't edit them in the code. The widget pulls them in automatically. To adjust them, go to Channels in the sidebar and open your web channel.

Personalizing the Widget for Known Users (Advanced)

Please note that this optional step needs a developer because it involves your website's code.

By default, every visitor is anonymous, and each browser tab is a fresh, separate conversation. If your website already knows who someone is (because they're signed in), you can hand that info to the widget. Then the bot greets them by name, matches them to their record in your PSA, and keeps their chat history with them across visits. It's the website version of the personalization that UCP, Teams, and Slack get automatically, since those users are already signed in.

To do it, your developer adds a short script right after the widget tag that fills in the person's details:

HTML:
<script>
  document.getElementById('chatbox').userInfo = {
    email: "logged-in-user@theircompany.com",
    displayName: "Jane Doe",
    companyName: "Acme Inc"
  };
</script>

Your developer swaps those three values for the real ones from whoever is signed into your site. The widget handles the rest.

There's also a lighter option, a user attribute on the tag that just remembers a returning visitor without passing their full details. Confirm the exact attribute with your developer before using it.

Content Security Policy

If your site uses strict CSP headers, ensure these sources are permitted: 

  • script-src should allow https://cdn.chatstyle.ai
  • style-src should allow https://cdn.chatstyle 
  • connect-src should allow WebSocket connections to the SignalR service.

Most sites don't need to worry about this - it only applies if you've explicitly configured CSP headers.

Mobile Behavior

The widget detects mobile devices automatically and adapts. On screens under 768px wide, the chat window adjusts to fit the screen, touch events are fully supported, and auto-focus on the input field is disabled to prevent keyboard scroll issues.

The floating bubble (default widget mode) works well on mobile with no special configuration. If you're using embedded mode, make sure the container element is sized appropriately for smaller screens.

Tip: Test on both iOS Safari and Android Chrome before going live. These are the two most common mobile browsers your end users will have.

Verification

After adding the snippet to your site:

  1. Open the page in a browser and confirm the chat bubble appears
  2. Click the bubble and verify the conversation starts
  3. Walk through the Dialog - submit a test issue and confirm a ticket is created in your PSA
  4. Test on a mobile device to confirm the widget adapts
  5. If you set up domain restrictions, try loading the page from a different domain to confirm it's blocked

Troubleshooting

The chat bubble doesn't appear. 

  • Check the browser console for errors. The most common causes: the snippet is pasted in the wrong location (put it before </body>), the channel ID is incorrect, or your site doesn't use HTTPS.

The widget loads but the conversation doesn't start. 

  • Check that autoStart is set to true in the options (it is by default). Also verify the channel is active in the admin portal - a disabled channel won't respond.

CSP errors in the browser console. 

  • If you see "Refused to load" errors, your Content Security Policy is blocking the widget's resources. Add the CDN and WebSocket domains to your CSP headers as described above.

The widget appears on pages where I don't want it. 

  • The snippet runs on every page where it's included. If you only want Chat on certain pages, add the snippet to those pages only - not to a global template or layout file.

End user identity isn't being picked up. 

  • Make sure the userInfo object is set before the end user opens the chat. If you're setting it asynchronously (after page load), the widget may have already started an anonymous session. Set identity as early as possible in the page lifecycle.

If you are still having trouble, we're here to help! Submit a ticket here for assistance, and don't forget to check our status page to ensure there are no outages in your area.

Related articles

Comments

0 comments

Article is closed for comments.