Documentation

Quickstart

Drop the chat widget on any HTML page in under five minutes.

The fastest way to get the widget running is the script-tag flavour. It works on any page that can run JavaScript — a static site, a CMS template, a Shopify theme, a Webflow page — without a build step.

Before you start

You need three values from AppMint:

  • orgId — your tenant id (the same orgid used everywhere else in AppEngine).
  • configId — the id of a chat config record. Create one in the admin UI under Chat > Configs, or POST /repository/create with datatype: 'chat-config'.
  • appId — a label for the surface the widget runs on (chat-client, storefront, support, etc.). It scopes events for analytics.

You can grab a working set from the demo build by reading the source of chat-demo.html in a deployed bundle.

  1. 1

    Add a container element

    Paste this anywhere on the page where the chat bubble should anchor. The widget positions itself fixed to the viewport regardless, so the container can sit at the bottom of <body>.

    <div id="my-chat-container"></div>
  2. 2

    Load the bundle and call init

    Add the script tag and an initializeChat() callback that runs as soon as the bundle is loaded. The widget exposes itself globally as AppmintChat.

    <script>
  function initializeChat() {
    AppmintChat.init({
      containerId: 'my-chat-container',
      orgId: 'your-org-id',
      configId: '67169ccce05fcd6eb50e6dff',
      appId: 'chat-client',
      appKey: 'hbfn75kfwmjm55vv0wi5',
      theme: 'light',
      language: 'en'
    });
  }

  function handleError() {
    console.error('Failed to load the AppmintChat script.');
  }
</script>

<link rel="stylesheet" href="https://web.appmint.space/chat-client/static/css/main.css">
<script
  src="https://web.appmint.space/chat-client/appmint-chat.js"
  onload="initializeChat()"
  onerror="handleError()"
></script>

    That's it. Reload the page and the bubble appears in the bottom-right corner.

  3. 3

    Send a test message

    Click the bubble. The first time a visitor opens the panel they see the welcome screen, then a registration form (name, email, optional phone). Submitting the form creates a guest customer in AppEngine, stores { token, user } in localStorage, and opens the conversation.

    Type a message and press Enter. If the chat config has an AI assistant attached, you'll see the assistant streaming a reply. Otherwise the message lands in the agent queue and waits for assignment.

What just happened

The script does five things in order:

  1. Mounts a React tree inside #my-chat-container (or in a generated appmint-chat-client div if you skip containerId).
  2. Calls GET /repository/find/chat-config against AppEngine to load your configId and applies theming, availability, and welcome content.
  3. If the visitor already has a session in localStorage, it restores { token, user } and routes them to the correct screen (/, /register, /chat).
  4. Tracks the page view via trackPageView() so AppMint can correlate visitors across pages.
  5. Opens a Socket.IO connection on the first authenticated event (queue request, message send, or status change) — see AppEngine integration.

Customisation knobs

Every option you can pass to init is listed on the Configuration page. The most common knobs:

  • theme — light or dark.
  • language — any locale present in src/locales/. Defaults to the browser language via i18next-browser-languagedetector.
  • defaultPath — /, /chat, /help, /setting. Forces the panel to land on a specific screen.
  • mode — chat (default) or qa for the Q&A variant.
Cache busting

The CDN URL appmint-chat.js is rewritten by update-script-hashes.js after every build, so customers always pull the latest bundle. If you self-host the build output, run that script (or copy it manually) so the hashed CRA filename is also available as main.js.

Where to go next