Web widget

Technical names such as window.SingChat belong to the widget and API. Keep them exactly as written in your code.

The web widget is a single script, widget.js, served from askais.com. It adds a chat launcher to your pages and draws the chat window inside a Shadow DOM, so your site's styles and the widget's styles stay apart.

Add it to your site

Paste this before </body> on every page where the chat should appear. Your App ID is in Settings → Inboxes.

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  async></script>

data-base-url is required on your own site: without it the widget looks for its server on your domain instead of askais.com.

⚠️ Load widget.js from askais.com

Do not download widget.js or bundle it into your own code. Loaded from askais.com, it always runs the current version; a copy stays frozen and misses every fix and new feature.

Script attributes

Everything is set with data- attributes on the script tag:

• data-app-id — Required. The App ID of your inbox.
• data-base-url — Required on your site. Always https://askais.com.
• data-locale — Optional. Forces the widget language, for example ja or zh-Hant. Leave it out and the widget follows the visitor's device language, then your page's lang.
• data-external-id — Your ID for a signed-in user.
• data-email — The user's email, shown to your team.
• data-name — The user's name, shown to your team.
• data-avatar-url — Link to the user's profile picture.
• data-hmac — Identity signature, see below.
• data-attrs — Extra details as JSON, for example {"plan":"Pro"}, shown to your team in the visitor's profile. Invalid JSON is ignored.

data-embed, data-platform, data-app-version and data-device-model are set by the in-app chat page. See In-app chat (WebView).

Signed-in visitors

For a signed-in user, add their details to the script tag. Your team sees who they are talking to, and the chat follows the user to other devices:

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  data-external-id="user_123"
  data-email="ada@example.com"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

Without data-external-id, the widget gives each browser its own anonymous ID, kept in the browser's local storage, so the chat history survives page reloads there. If the inbox has a pre-chat form, anonymous visitors fill it in before the chat starts.

Verified identity (HMAC)

• hmac is the HMAC-SHA256 of the externalId, keyed with the inbox secret key, written as lowercase hex.
• Compute it on your server. The secret key never goes into a page or an app.
• The secret key is shown once when you create the inbox, and again when you rotate it under Settings → Inboxes. Rotating it makes every old signature invalid.
• Always send data-external-id together with data-hmac. The signature is checked against the external ID, so a signature over the email alone is rejected.
• With a wrong signature the widget cannot connect. Without data-hmac, the details are taken as the page gives them, so anyone who can change the page could claim to be someone else.

Example for Node.js:

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

Starting the widget from JavaScript

To start the widget yourself, for example once your page knows who the user is, load the script without data-app-id and call window.SingChat.start() after it has loaded:

<script src="https://askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "ada@example.com",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

start() is the only method the script provides. There are no methods to open, close or listen to the widget; visitors open it from the launcher.

Appearance and behavior

• Settings → Inboxes, then expand an inbox: primary color and text color, position (bottom right or bottom left), bubble size, light or dark background, window title and subtitle, with a live preview.
• Pre-chat form (same place): ask anonymous visitors for their email, name, phone or company before the chat starts.
• Allowed origins (same place): the websites that may load this inbox's widget. An empty list allows any site.
• Widget branding (same place): the “Powered by” line at the bottom of the chat. Whether you can hide it or show your own name there depends on your plan.
• The AI welcome message is set under AI Agent, the clickable FAQ bubbles under Settings → FAQs, and articles under Help Center.

Security

• The App ID is public and safe in your HTML.
• The inbox secret key belongs on your server only.
• Use verified identity (HMAC) whenever the page knows who the user is.
• Limit allowed origins to your own domains so the widget cannot be loaded on other sites.