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="[email protected]"
  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 (the inbox's ⋮ menu → Rotate secret key). Use the whole key, including the sk_ prefix. Rotating it makes every old signature invalid.
• Always send data-external-id together with data-hmac, and sign exactly that value. The widget always sends an external ID (it makes up an anonymous one if you pass none), so a signature over the email alone never verifies anyone.
• A wrong or missing signature never stops the chat: the visitor can still talk to you, but is treated as unverified. Unverified details are taken as the page gives them, so anyone who can change the page could claim to be someone else, unless you turn on Require identity verification, which treats unverified visitors as anonymous visitors who don't see earlier conversations.

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: "[email protected]",
    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.