Widget Installation

The GudDesk chat widget lets your customers start conversations directly from your website. Installation takes less than a minute.

Basic Installation

Add this snippet before the closing </body> tag of your website:

<script>
  window.GudDeskSettings = {
    appId: "gd_pub_xxxxxxxxxxxxxxxx"
  };
</script>
<script src="https://cdn.guddesk.com/widget.js" async></script>

Replace the gd_pub_ value with your actual App ID, found in Dashboard > Settings > Widget.

Self-Hosted Installation

If you're self-hosting GudDesk, point the widget to your own instance:

<script>
  window.GudDeskSettings = {
    appId: "gd_pub_xxxxxxxxxxxxxxxx",
    baseUrl: "https://your-guddesk-domain.com"
  };
</script>
<script src="https://your-guddesk-domain.com/widget.js" async></script>

React / Next.js

For React-based apps, you can load the widget in a layout or root component:

"use client";
 
import { useEffect } from "react";
 
export function GudDeskWidget() {
  useEffect(() => {
    window.GudDeskSettings = {
      appId: process.env.NEXT_PUBLIC_GUDDESK_PUB_KEY,
    };
 
    const script = document.createElement("script");
    script.src = "https://cdn.guddesk.com/widget.js";
    script.async = true;
    document.body.appendChild(script);
 
    return () => {
      document.body.removeChild(script);
      window.GudDesk?.destroy();
    };
  }, []);
 
  return null;
}

JavaScript API

Once loaded, the widget exposes a global window.GudDesk object:

// Open the chat widget
window.GudDesk.open();
 
// Close the chat widget
window.GudDesk.close();
 
// Identify a logged-in user
window.GudDesk.identify({
  userId: "usr_12345",
  name: "Jane Doe",
  email: "customer@example.com",
});
 
// Destroy the widget instance
window.GudDesk.destroy();

Passing User Data

Call identify() whenever a user logs in or their details become available. For single-page apps, call it after authentication completes. For server-rendered pages, call it on page load when the user is already logged in.

// After your authentication flow completes
onLoginSuccess(user) {
  window.GudDesk.identify({
    userId: user.id,          // required for identity verification
    name: user.displayName,
    email: user.email,
    metadata: {               // optional custom data
      plan: user.plan,
      company: user.company,
    },
  });
}

If the user is not yet logged in, the widget works in anonymous mode. You can call identify() later once they authenticate — existing conversations will be linked to the identified user.

Identity Verification

Identity verification prevents impersonation by ensuring that user data passed to the widget was generated by your server. It uses HMAC-SHA256 — the same standard used by Intercom, Zendesk, and other customer support platforms.

How It Works

1. You generate a secret key in Dashboard > Settings > Widget > Identity Verification
2. Your server computes an HMAC hash of the user's ID using the secret
3. You pass the hash to the widget alongside the user data
4. GudDesk verifies the hash before accepting the identity

Server-Side Setup

Generate the HMAC on your backend — never expose the secret in client-side code.

// Node.js
import { createHmac } from "crypto";
 
const userHash = createHmac("sha256", process.env.GUDDESK_IDENTITY_SECRET)
  .update(user.id)
  .digest("hex");

# Python
import hmac, hashlib
 
user_hash = hmac.new(
    GUDDESK_IDENTITY_SECRET.encode(),
    user_id.encode(),
    hashlib.sha256
).hexdigest()

# Ruby
user_hash = OpenSSL::HMAC.hexdigest("sha256", ENV["GUDDESK_IDENTITY_SECRET"], user.id)

Client-Side Setup

Pass the userHash alongside the user info:

window.GudDesk.identify({
  userId: "usr_12345",
  name: "Jane Doe",
  email: "jane@example.com",
  userHash: "abc123...", // HMAC from your server
});

Verify Installation

After adding the snippet:

1. Open your website in a browser
2. You should see the chat bubble in the bottom-right corner
3. Click it and send a test message
4. Check your GudDesk inbox — the message should appear

If the widget doesn't appear, check the browser console for errors and verify your App ID is correct.

Next Steps

• Customize the widget appearance and behavior
• Set up your inbox to manage incoming conversations