widget-setup

tawk.to Widget Setup

Reference: https://developer.tawk.to/jsapi/

Getting the IDs

The embed snippet needs a property ID and a widget ID. The user finds both in the tawk.to dashboard: Administration → Channels → Chat Widget (the embed code shown there contains embed.tawk.to/<propertyId>/<widgetId>). If the MCP tools are configured, tawk_list_properties returns property IDs too.

Embed snippet (plain HTML)

Place before </body>:

<script type="text/javascript">
  var Tawk_API = Tawk_API || {},
    Tawk_LoadStart = new Date();
  (function () {
    var s1 = document.createElement("script"),
      s0 = document.getElementsByTagName("script")[0];
    s1.async = true;
    s1.src = "https://embed.tawk.to/PROPERTY_ID/WIDGET_ID";
    s1.charset = "UTF-8";
    s1.setAttribute("crossorigin", "*");
    s0.parentNode.insertBefore(s1, s0);
  })();
</script>

Replace PROPERTY_ID and WIDGET_ID with the user's real values (widget ID is often default).

React / Next.js

For Next.js, use next/script in the root layout (App Router) or _app (Pages Router):

import Script from "next/script";

export function TawkWidget() {
  return (
    <Script id="tawk" strategy="lazyOnload">
      {`var Tawk_API = Tawk_API || {}, Tawk_LoadStart = new Date();
        (function () {
          var s1 = document.createElement("script"),
            s0 = document.getElementsByTagName("script")[0];
          s1.async = true;
          s1.src = "https://embed.tawk.to/PROPERTY_ID/WIDGET_ID";
          s1.charset = "UTF-8";
          s1.setAttribute("crossorigin", "*");
          s0.parentNode.insertBefore(s1, s0);
        })();`}
    </Script>
  );
}

For plain React, inject the same script in a useEffect(() => { ... }, []) hook.

Common Tawk_API customizations

All of these go BEFORE the embed script loads (or inside Tawk_API.onLoad):

// Identify the visitor (name/email shown to agents)
Tawk_API.visitor = { name: "Jane Doe", email: "[email protected]" };

// React to lifecycle events
Tawk_API.onLoad = function () {
  // widget ready — safe to call API methods from here
};
Tawk_API.onChatStarted = function () {};
Tawk_API.onChatEnded = function () {};

// Programmatic control (only after onLoad)
Tawk_API.maximize();
Tawk_API.minimize();
Tawk_API.hideWidget();
Tawk_API.showWidget();

// Attach attributes / events / tags to the visitor (after onLoad)
Tawk_API.setAttributes({ plan: "pro", userId: "u_123" }, function (error) {});
Tawk_API.addEvent("checkout-started", { cartValue: 99 }, function (error) {});
Tawk_API.addTags(["vip"], function (error) {});

Secure mode

Secure mode prevents visitors from impersonating each other. The hash MUST be computed server-side (the JS API key must never reach the browser). The key for hashing comes from Administration → Channels → Chat Widget → Secure Mode in the tawk.to dashboard — it is NOT the REST API key.

Server-side (Node):

const crypto = require("crypto");

function tawkVisitorHash(email, jsApiKey) {
  return crypto.createHmac("sha256", jsApiKey).update(email).digest("hex");
}

Client-side:

Tawk_API.visitor = {
  name: user.name,
  email: user.email,
  hash: hashFromServer, // value computed server-side above
};

Checklist when helping a user

1. Ask which framework (plain HTML / React / Next.js / other) and adapt the snippet.
2. Get real property + widget IDs — never leave placeholders in delivered code.
3. If they identify logged-in users, recommend secure mode and wire the server-side hash.
4. Keep all keys out of client code and out of version control.