How to Install the Cloud Chat Web Widget: Public, with Data, or Logged-in Area (HMAC)

When to Use

• You want to add the Cloud Chat widget to any page of your website

• You want to automatically pass contact data (name, email, phone, attributes) without the client typing

• You want to validate the user's identity (HMAC) to prevent impersonation

• You want to allow multiple simultaneous conversations and access to history within the widget

• You want to restrict the widget to specific domains (e.g., production only)

Prerequisites

• Be logged in as admin on Cloud Chat

• Access to the source code of the website where the widget will be installed

• For Scenario 3 (logged-in area with HMAC): a custom backend to generate the identifier_hash — it cannot be done on the frontend (exposes the secret key)

About this Tutorial

This article covers the full cycle of installing the Cloud Chat Web Widget. Before following the coding steps, you need to decide which of the 3 scenarios fits your use case — they have very different requirements and complexity.

Which scenario is yours?

Common Step — Create the Website Inbox

Before configuring any scenario, you need to create a Website-type inbox in Cloud Chat. The process is the same for all 3 scenarios.

1. Access the Inboxes Screen

In the Cloud Chat dashboard, go to Settings → Inboxes and click on the Add Inbox button (top right corner).

2. Choose the Website Channel

Select the Website card from the available channels.

3. Configure the Website Channel

Fill in the fields:

• Site Name — name shown to the customer (e.g., "Cloud Humans")

• Website Domain — domain where the widget will run (e.g., cloudhumans.com)

• Widget Color — primary color of the button and header

• Welcome Title — initial widget title (e.g., "Hello!")

• Welcome Message — greeting message

• Activate Channel Greeting — whether to send an automatic message at the start of chat

Click Create Inbox.

4. Add Agents

Select the agents who will have access to this inbox. As an administrator, add yourself if you want to see all conversations.

Click Add Agents.

5. Script Configuration

On the final screen (“Your inbox is ready!”), Cloud Chat displays the basic installation script for the widget. However, other configuration options are available depending on your scenario.

Click More Settings. In this section, you'll see the three available script options for installation, which we will explain below.

Scenario 1 — Public Web Widget (no customer data passing)

Use when the widget is on a public page (landing, blog, institutional site). The customer types their name/email/phone at the start.

How to Install

Paste the script copied in the Common Step (Step 5) just before the closing </body> tag of your page's HTML:

Scenario 2 — Web Widget passing customer data, outside logged-in area

Use when you already know the contact but the page does not require login. Examples:

• Unique link sent via email or WhatsApp with the identifier in the URL

• Post-registration page (customer just filled out a form)

• Page accessed via CRM campaign deep link

Here, you want to pre-fill name, email, phone, and custom attributes without the customer typing.

How to Install

Scenario 3 — Logged-in Web Widget (with HMAC + optional multiple conversations)

Use when the widget is inside a logged-in area (client portal, dashboard, authenticated app). HMAC is mandatory here.

This scenario is also the only one where enabling multiple conversations + history makes sense.

3.1 — How HMAC Works

Validation uses HMAC SHA-256: a code generated from the user's identifier combined with a secret key (token) of the inbox.

3.2 — Copy the inbox token

In Settings → Inboxes → (your Website inbox) → Advanced Settings → User Identity Validation → Copy.

This token is secret — store it only in your backend, never in the frontend.

3.3 — Calculate identifier_hash on backend

When the user authenticates in your system, the backend calculates:

identifier_hash = HMAC_SHA256(inbox_token, identifier)

Where identifier is the user's unique ID (internal UUID, corporate email, etc).

Server-side examples:

// Node.js
const crypto = require('crypto');
const hash = crypto
  .createHmac('sha256', '<inbox-token>')
  .update('<identifier>')
  .digest('hex');

# Python
import hashlib, hmac
hash = hmac.new(b'<inbox-token>', b'<identifier>', hashlib.sha256).hexdigest()

// PHP
$identifier_hash = hash_hmac('sha256', '<identifier>', '<inbox-token>');

3.4 — Send the hash to the widget via setUser

<script>
  (function(d,t) {
    var BASE_URL="https://cloudchat2.cloudhumans.com";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g,s);

    g.onload=function(){
      window.cloudchatSDK.run({
        websiteToken: 'YOUR_TOKEN_HERE',
        baseUrl: BASE_URL
      });

      window.addEventListener('cloudchat:ready', function() {
        window.$cloudchat.setUser('<user-identifier>', {
          identifier_hash: '<hash-generated-backend>',
          email: '[email protected]',
          name: 'João da Silva',
          phone_number: '+5511999999999'
        });
      });
    }
  })(document,"script");
</script>

3.5 — Force validation in the inbox

In Advanced Settings, enable "Force user identity validation". Requests without a valid identifier_hash are rejected.

3.6 — (Optional) Enable multiple conversations and history

With HMAC enabled, you can activate the feature of multiple conversations + history: the same user can have several open conversations simultaneously and see the history of closed conversations within the widget.

Useful for SaaS, B2B, or e-commerce with high repurchase/retargeting.

How the user sees: the widget will now display two tabs — Active Conversations (open) and Conversation History (closed, with date range and ticket ID search; loads 5 at a time).

Demonstrative videos:

How to enable:

1. In Cloud Chat dashboard, go to Inboxes → (your Website inbox) → Settings

2. Enable the Multiple conversations per user flag

3. Copy the new script displayed after activation — it already includes user_id and identifier_hash in the correct format

4. Replace the current page script with the new one

Domain Validation (optional, all scenarios)

Configure the domains where the widget can operate — useful to prevent usage outside authorized domains (staging, unauthorized third parties).

In Inboxes → (your inbox) → Settings, under the Domain Validation section:

How to Test

1. Open the page with the widget installed

2. Check if the widget appears at the corner of the screen

3. Scenarios 2 and 3: verify that name, email, phone, and attributes already appear pre-filled without customer input

4. Scenarios 2 and 3: test with at least 2 different users — open the widget with one, then with another, and check if they appear as separate contacts (not merged into one). If they appear merged, the identifier is fixed — fix it before deploying to production

5. Scenario 3: test with an invalid identifier_hash and verify that the widget rejects the request when "Force validation" is enabled

6. Scenario 3 with multiple conversations: open two tickets in parallel and check that they appear as separate conversations inside the widget

Frequently Asked Questions

What happens if there is already previous contact information?

The new data sent via script overwrites the old data. The most recent information prevails.

What if I make a mistake in a custom field name?

No error is thrown. The incorrect field is silently ignored. Only existing fields are updated.

Can I pass conversation attributes as well?

What formatting does the widget accept?

The Widget accepts most Markdown formats:

• Bold / Strikethrough / Italic

• Code block

• Links

• Images

• Bullet points

Can I use HMAC without enabling multiple conversations?

Yes. HMAC is an independent security layer — you can enable only HMAC (Scenario 3, steps 3.1 to 3.5) without enabling multiple conversations (step 3.6). The reverse is not recommended.

Can I use this in mobile apps?

Yes, via WebView. See How to integrate the Web Widget into mobile apps.

Notes

• To share the widget session across browser tabs: How to share the Web Widget session between browser tabs

• To use the widget in mobile apps via WebView: How to integrate the Web Widget into mobile applications

• To create custom attributes before passing via script: How to create custom contact and conversation fields

• To enable conversation continuity via email: How to enable conversation continuity via email

• To activate the widget in the Help Portal: How to activate the Web Widget in the Help Portal