Skip to Content
Developer docsBeta
Website & app chat

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:

  1. the Mawgood's base look;
  2. its platform override (the tab of the SDK that draws it: web, flutter or reactNative);
  3. 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

FieldValuesDefault
shapecircle, rounded, pill (with a label)circle
sizes, m, l, or 32–120 pxm
iconchat, avatar (the Mawgood's photo), image (imageUrl)chat
imageUrlAn https imagenull
labelUp to 30 characters (the pill's text)null
positionbottom-start, bottom-endbottom-end
offset{ x, y }, 0–400 px from the edges{ 20, 20 }
mobileOffsetThe same, on phones (web only; apps use offset){ 16, 16 }
hiddentrue: no launcher, open it from your own buttonfalse
unreadBadgeUnread count on the launchertrue
animationnone, fade, pop, slidepop

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

FieldValuesDefault
radiusbubble 0–32, window 0–40, button 0–32 (px)16, 16, 12
font.familysystem, or customsystem
font.nameThe family name: the CSS family on web, a font your app bundles on mobilenull
font.webFontUrlWeb only: an https font file (.woff2, .woff, .ttf, .otf), never a stylesheetnull
baseSize12–2015
densitycompact, comfortablecomfortable

A custom font on mobile must be bundled by your app.

window

FieldValuesDefault
modefloating, fullscreen, sideSheet (web only), bottomSheet (apps only); each falls back to floating elsewherefloating
width300–720 px (desktop web; caps the floating panel in apps)380
height400–1000 px620
titleUp to 60 characters; null is the Mawgood's namenull
subtitleUp to 80; null is «بيرد في ثواني» / "Replies in seconds"null
avatarmawgood, logo (for now it shows the Mawgood's photo too), nonemawgood
showOnlineThe online dottrue
showCloseThe close buttontrue
showMinimizeThe minimize buttonfalse

content

FieldValuesDefault
welcomeUp to 500 characters, at the top of the thread (never sent)null
startersUp to 6 suggested first messages, 60 characters each[]
awayUp to 300; shown while no one is onlinenull
placeholderUp to 60; the composer's hintnull
privacyTextUp to 200; the privacy line, linked to the privacy page set on the cardnull
poweredBy«Powered by Mawgood»; no plan can hide it yettrue

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

FieldValuesDefault
autoOpenafterSeconds 0–600 (null = never opens by itself), and match: only on these pages or screens (empty = all)null, []
nudgesUp to 10 { text, match, afterSeconds }: a short bubble beside the launcher, shown locally, never sent[]
soundA sound on a new messagetrue
hapticsApps only: a light vibration on a new messagetrue
keepOpenWeb only: stays open across page navigationtrue
includeWeb only: show only on pages matching these patterns (empty = every page); up to 50[]
excludeWeb 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

SDKOption
Web (React)slots={{ renderHeader, renderMessage, renderEmpty }}: each returns an HTMLElement, or null for the default. On the element: el.slots = { … }.
React NativerenderHeader={({ state, close }) => …}, renderMessage={(message, theme) => …} (null = the default), renderEmpty={({ welcome, starters, send }) => …}
FlutterMawgoodChatOptions(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.

On this page