Customization
Every look setting, how the dashboard and your code combine, custom launchers, your own renderers and headless mode.
Where the look comes from
The look is set per Mawgood on the Chat look page (the card's Customize the look,
/agents/<id>/chat-look), with a Base tab and one tab per platform (Website, Flutter, React Native). Each bubble
wears, field by field, the last one that sets it:
- the Mawgood's base look;
- its platform override (the tab of the SDK that draws it:
web,flutterorreactNative); - your in-code options (
look), last.
Objects merge field by field; a list (starters, nudges, URL patterns) replaces the one under it as a whole. When you save the look in the dashboard, every open bubble restyles within seconds, with no release of your site or app.
// Script tag: window.Mawgood.update(…); npm: init({ look }) or mawgood.update(…)
Mawgood.update({ window: { mode: 'sideSheet' }, launcher: { shape: 'pill', label: 'Ask us' } });
// React / Vue: <MawgoodChat look={{ … }} /> Element: el.look = { … }In Flutter, a field that may be null is set with Nullable(x); Nullable(null) sets it back to the
SDK's default text, and leaving the field out keeps what's under it.
The look, group by group
Text fields left null use the SDK's own text in the bubble's language.
launcher
| Field | Values | Default |
|---|---|---|
shape | circle, rounded, pill (with a label) | circle |
size | s, m, l, or 32–120 px | m |
icon | chat, avatar (the Mawgood's photo), image (imageUrl) | chat |
imageUrl | An https image | null |
label | Up to 30 characters (the pill's text) | null |
position | bottom-start, bottom-end | bottom-end |
offset | { x, y }, 0–400 px from the edges | { 20, 20 } |
mobileOffset | The same, on phones (web only; apps use offset) | { 16, 16 } |
hidden | true: no launcher, open it from your own button | false |
unreadBadge | Unread count on the launcher | true |
animation | none, fade, pop, slide | pop |
colors
mode is light, dark or system (default light), with a full light set and a dark set.
Each set has primary, launcherBackground, launcherIcon, headerBackground, headerText,
customerBubble, customerText, mawgoodBubble, mawgoodText, staffBubble, staffText,
background, input, inputText and link, each #RRGGBB or #RRGGBBAA. The defaults are
Mawgood's brand colours. launcherBackground, headerBackground and customerBubble may be
null: they follow primary, so the brand colour alone recolours the launcher, the header and the
customer's bubble. They're null in the default light set; the dark set keeps its dark header and
deep-green launcher and bubble.
shape
| Field | Values | Default |
|---|---|---|
radius | bubble 0–32, window 0–40, button 0–32 (px) | 16, 16, 12 |
font.family | system, or custom | system |
font.name | The family name: the CSS family on web, a font your app bundles on mobile | null |
font.webFontUrl | Web only: an https font file (.woff2, .woff, .ttf, .otf), never a stylesheet | null |
baseSize | 12–20 | 15 |
density | compact, comfortable | comfortable |
A custom font on mobile must be bundled by your app.
window
| Field | Values | Default |
|---|---|---|
mode | floating, fullscreen, sideSheet (web only), bottomSheet (apps only); each falls back to floating elsewhere | floating |
width | 300–720 px (desktop web; caps the floating panel in apps) | 380 |
height | 400–1000 px | 620 |
title | Up to 60 characters; null is the Mawgood's name | null |
subtitle | Up to 80; null is «بيرد في ثواني» / "Replies in seconds" | null |
avatar | mawgood, logo (for now it shows the Mawgood's photo too), none | mawgood |
showOnline | The online dot | true |
showClose | The close button | true |
showMinimize | The minimize button | false |
content
| Field | Values | Default |
|---|---|---|
welcome | Up to 500 characters, at the top of the thread (never sent) | null |
starters | Up to 6 suggested first messages, 60 characters each | [] |
away | Up to 300; shown while no one is online | null |
placeholder | Up to 60; the composer's hint | null |
privacyText | Up to 200; the privacy line, linked to the privacy page set on the card | null |
poweredBy | «Powered by Mawgood»; no plan can hide it yet | true |
language
locale is auto (the page's or app's language), ar or en. direction is auto (Arabic
right-to-left, English left-to-right), rtl or ltr. Defaults: auto, auto.
behaviour
| Field | Values | Default |
|---|---|---|
autoOpen | afterSeconds 0–600 (null = never opens by itself), and match: only on these pages or screens (empty = all) | null, [] |
nudges | Up to 10 { text, match, afterSeconds }: a short bubble beside the launcher, shown locally, never sent | [] |
sound | A sound on a new message | true |
haptics | Apps only: a light vibration on a new message | true |
keepOpen | Web only: stays open across page navigation | true |
include | Web only: show only on pages matching these patterns (empty = every page); up to 50 | [] |
exclude | Web only: never on pages matching these; up to 50 | [] |
A pattern is a URL or a path with * wildcards on web, and a screen name in apps (the one you set
with setPage('product') or setScreen('product')).
features
attachments, voiceNotes, emoji, rating (👍 / 👎 on the Mawgood's replies), history (load
older messages) and newConversation («ابدأ محادثة جديدة»). All default to true except rating.
Your own launcher
Set launcher.hidden: true (in the dashboard or in code), then open the chat yourself:
document.querySelector('#help').addEventListener('click', () => Mawgood.open());
// React: const mawgood = useMawgood(); mawgood?.open();Your own header, messages and empty state
| SDK | Option |
|---|---|
| Web (React) | slots={{ renderHeader, renderMessage, renderEmpty }}: each returns an HTMLElement, or null for the default. On the element: el.slots = { … }. |
| React Native | renderHeader={({ state, close }) => …}, renderMessage={(message, theme) => …} (null = the default), renderEmpty={({ welcome, starters, send }) => …} |
| Flutter | MawgoodChatOptions(headerBuilder: …, messageBuilders: {MawgoodMessageKind.catalog: …}, emptyStateBuilder: …, style: MawgoodChatStyle.cupertino) |
Flutter's MawgoodMessageKind is text, image, file, voice, buttons, catalog or
payment; the style is Material 3 by default.
Headless
To draw everything yourself, use the client with no UI. It gives the session, the message stream
and send(), and keeps the offline outbox and realtime connection like the SDKs do.
// npm install @mawgood/chat-core (React Native: re-exported by @mawgood/chat-react-native)
import { MawgoodChatClient } from '@mawgood/chat-core';
const client = new MawgoodChatClient({
siteKey: 'mwg_pk_live_…',
mawgoodId: 'mw_ag_…',
platform: 'web',
storage: localStorage, // default: memory (nothing kept)
});
client.on('message', (m) => render(m));
await client.start();
client.send('Hi');A native app using @mawgood/chat-core directly must pass app: 'ios:<bundle id>' or
'android:<package>' and a persistent storage.