Skip to Content
Developer docsBeta
Website & app chat

Website

Add the bubble to any website with one script tag, or with npm in React, Next.js or Vue.

The web bubble is drawn in your page inside a Shadow DOM: your CSS can't break it, and its CSS never leaks into your page. It works on desktop and opens full screen on phones.

Allow your site

In your Mawgood › Overview and channels › Website & app chat, create a site key and add your site's origin under Allowed sites and apps: https://shop.example.com, or https://*.example.com for every subdomain (not example.com itself; add it too if you need it). An origin is a scheme and a host, with no path. Trying it on your machine? Use a test key: it always works on localhost, 127.0.0.1 and [::1], on any port. A live key never does.

Install

Pick one. Each needs only the site key and the Mawgood ID.

<!-- Before </body>, on every page -->
<script
  src="https://cdn.mawgood.ai/chat/v1.js"
  data-site-key="mwg_pk_live_…"
  data-mawgood-id="mw_ag_…"
  async
></script>

Check it

Open your site: the launcher shows where the look puts it (bottom end by default). Write a message and the Mawgood answers. If nothing shows, open the browser console: setup mistakes are printed there as [Mawgood chat] …, then see Troubleshooting.

Options

Script tagReact / Vue propinit() optionWhat it does
data-site-keysiteKey / site-keysiteKeyRequired. The site key.
data-mawgood-idmawgoodId / mawgood-idmawgoodIdRequired. The Mawgood ID.
data-environmentenvironmentenvironmentproduction (default) or staging, for testing against staging.mawgood.ai.
data-localelocalelocalear or en. Default: the look's language, else the page's lang.
data-api-base-urlapiBaseUrlapiBaseUrlAnother API host (local development).
data-realtime-urlrealtimeUrlrealtimeUrlAnother realtime host; empty means Server-Sent Events only.
data-strip-querystripQuery / strip-querystripQueryThe page URL the Mawgood hears leaves out the query string (see below).
—looklookYour in-code look (Customization).
—identityidentityA signed customer (Identifying customers).
—slots (React)—Your own header, message renderer or empty state.
——containerWhere the bubble is added (default document.body).

The script tag sets window.Mawgood once it has loaded. To call it before that, put a stub first; queued calls run when the script is ready (the page itself is followed automatically; no setPage needed):

<script>
  window.Mawgood = window.Mawgood || { q: [] };
  Mawgood.q.push(['setAttributes', { plan: 'gold' }]);
  document.querySelector('#help').addEventListener('click', () => Mawgood.q.push(['open']));
</script>

The custom element

@mawgood/chat-web also exports the element itself. Call defineMawgoodChat() once, then use the tag anywhere:

<mawgood-chat site-key="mwg_pk_live_…" mawgood-id="mw_ag_…" strip-query></mawgood-chat>

Its attributes are site-key, mawgood-id, environment, api-base-url, realtime-url, locale and strip-query, and its properties look, identity and slots. The Mawgood hears the page the customer is on: the URL without its #fragment (never sent), and without the query string too when you ask for it, in any of three ways:

<!-- Script tag -->
<script
  src="https://cdn.mawgood.ai/chat/v1.js"
  data-site-key="…"
  data-mawgood-id="…"
  data-strip-query
  async
></script>
<!-- Element -->
<mawgood-chat site-key="…" mawgood-id="…" strip-query></mawgood-chat>
// npm
init({ siteKey: '…', mawgoodId: '…', stripQuery: true });
// React: <MawgoodChat stripQuery … />   Vue: <MawgoodChat strip-query … />

data-strip-query with no value (or any value but "false") turns it on. Use it when your URLs carry customer data (emails, order tokens). Single-page sites are followed as they change URL.

Next

On this page