How to set up and install the Web Agent on your website

What is the Web Agent?

The Web Agent is a chat widget you embed on your website. It greets visitors, answers their questions instantly using your uploaded knowledge base, replies in their language, and hands the conversation over to your team whenever a human is needed. Every conversation, rating, and lead is captured in your dashboard.

Part 1 — Set up your agent in the dashboard

Open your Safqat dashboard and go to Web Agent → Setup. A guided 7-step wizard walks you through everything below. You can change any of these later from Web Agent → Settings.

Part 2 — Install it on your website

Once your agent is active, installing it is a copy-and-paste job. The snippet is two short lines of code that load the widget and connect it to your agent.

<script src="https://cdn.safqat.ai/widget.js" data-safqat-api-base="https://safqat.ai"></script>
<script>
  Safqat.init({
    agentId: "your-agent-id",
    apiBase: "https://safqat.ai"
  });
</script>

1. 1

   Copy your snippet from the dashboard

   Use the copy button so your real agent ID is included. The example above uses "your-agent-id" as a placeholder — yours will be a unique value.

2. 2

   Paste it into your website

   Add the snippet just before the closing </body> tag on every page where you want the chat to appear. On platforms like Shopify, WordPress, or Wix, paste it into the "custom code" or "header/footer scripts" section so it loads site-wide.

3. 3

   Publish and refresh

   Save and publish your site, then reload the page. A chat bubble appears in the corner — click it to start a conversation.

Safqat.init({
  agentId: "your-agent-id",
  apiBase: "https://safqat.ai",
  user: {
    id: currentUser.id,     // unique per visitor
    hash: currentUser.safqatHash, // signed on your server (below)
    name: currentUser.name,
    email: currentUser.email,
    // Optional: properties (shown in People, usable by the AI and for targeting)
    properties: { plan: currentUser.plan, orders: currentUser.orderCount }
  }
});

// Node.js — the secret never leaves your server
const crypto = require("crypto");
const safqatHash = crypto
  .createHmac("sha256", process.env.SAFQAT_IDENTITY_SECRET)
  .update(String(currentUser.id))
  .digest("hex");

Part 3 — Control the widget with JavaScript

Everything here is optional. Use it when your site is a single-page app, has its own login, or wants to open the chat from its own buttons.

<script>
  (function (w, d) {
    w.Safqat = w.Safqat || function () {
      (w.Safqat.q = w.Safqat.q || []).push(arguments);
    };
    var s = d.createElement("script");
    s.async = true;
    s.src = "https://cdn.safqat.ai/widget.js";
    s.setAttribute("data-safqat-api-base", "https://safqat.ai");
    d.head.appendChild(s);
  })(window, document);

  Safqat("init", { agentId: "your-agent-id", apiBase: "https://safqat.ai" });
</script>

Safqat.open();                    // open the chat (Messages tab)
Safqat.close();
Safqat.toggle();
Safqat.hide();                    // hide the launcher (e.g. you use your own button)
Safqat.show();                    // bring the launcher back
Safqat.showNewMessage("I have a question about my order"); // open with text prefilled

// Who the visitor is (login, user switch, language change)
Safqat.update({ user: { id: user.id, name: user.name, email: user.email }, locale: "en" });

// Properties for this visitor — merged; null deletes a key
Safqat.setProperties({ plan: "pro", seats: 5, trialEndsAt: null });

Safqat.shutdown();                // logout: remove the widget and forget this visitor

// Events: "ready" | "open" | "close" | "unreadCountChange" | "message"
const off = Safqat.on("unreadCountChange", ({ count }) => updateBadge(count));
off();                            // stop listening

// Conversions (thank-you / order-complete page)
Safqat.trackConversion({ agentId: "your-agent-id", orderId: "1042", amount: 49, currency: "USD" });

// React example — run whenever your auth state changes
useEffect(() => {
  if (!user) return;
  Safqat("update", {
    user: { id: user.id, name: user.name, email: user.email },
  });
  Safqat("setProperties", { plan: user.plan, stations: user.stationCount });
}, [user]);

async function handleLogout() {
  await signOut();
  Safqat("shutdown"); // forget this visitor on this browser
  // Optional: keep the chat available for anonymous visitors
  Safqat("init", { agentId: "your-agent-id", apiBase: "https://safqat.ai" });
}

Verify it's working

Before telling customers about it, do a quick check on your live site:

• The chat bubble appears on your published website
• Sending a test message gets an AI reply based on your knowledge base
• The conversation shows up in Web Agent → Conversations in your dashboard
• Your live domain is listed under allowed domains (otherwise the widget won't load)