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 tag | React / Vue prop | init() option | What it does |
|---|---|---|---|
data-site-key | siteKey / site-key | siteKey | Required. The site key. |
data-mawgood-id | mawgoodId / mawgood-id | mawgoodId | Required. The Mawgood ID. |
data-environment | environment | environment | production (default) or staging, for testing against staging.mawgood.ai. |
data-locale | locale | locale | ar or en. Default: the look's language, else the page's lang. |
data-api-base-url | apiBaseUrl | apiBaseUrl | Another API host (local development). |
data-realtime-url | realtimeUrl | realtimeUrl | Another realtime host; empty means Server-Sent Events only. |
data-strip-query | stripQuery / strip-query | stripQuery | The page URL the Mawgood hears leaves out the query string (see below). |
| — | look | look | Your in-code look (Customization). |
| — | identity | identity | A signed customer (Identifying customers). |
| — | slots (React) | — | Your own header, message renderer or empty state. |
| — | — | container | Where 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
- Events and methods:
open(),setUser(),onMessage… - Content-Security-Policy lines if your site sets a CSP.