Skip to Content
Developer docsBeta
Website & app chat

Events and methods

What each SDK lets you call, and what it tells you.

Every SDK has the same events and the same context calls, named for its platform.

EventWhen
open / closeThe chat window opened or closed.
messageA new message from the Mawgood or your team (not the customer's own).
unread changeThe number of the Mawgood's and team's messages the customer hasn't read changed.
handoffThe chat went to your team or back to the Mawgood (withTeam, teamOnline).
errorSomething failed: a refused key or site, the network, a file too big…
CallWhat it does
open / close / toggleOpens or closes the chat.
set userA signed customer.
set page / set screenWhere the customer is: { url, title } on web, a screen name in apps. The Mawgood reads it.
set attributesUp to 20 values the Mawgood may use ({ cart: 450 }): keys up to 40 characters, text values up to 200.
logoutForgets the customer and this device's chat, and starts anonymous.

Web

The script tag's window.Mawgood, what init() returns, and useMawgood() (React and Vue) are the same object:

MemberNotes
open(), close(), toggle()
setUser(identity)
setPage(page){ url?, title? } or a string. The page is followed by itself; a URL you pass also loses its #fragment (and its query with strip-query).
setAttributes(attributes)
logout()
update(look)Restyles in code, merged over what you set before.
on(event, listener), off(event, listener)on returns a function that removes the listener.
stateThe current state: status, messages, unread, open, connection…
element, destroy()The <mawgood-chat> element; destroy() removes it from the page.

React's useMawgood() is null until a bubble is mounted (mawgood?.open()). Vue's returns a shallowRef: use mawgood.value?.open().

Events for on(): open, close, message, unreadChange, handoff, error, and also typing, look (the look changed) and change (any state change).

const off = Mawgood.on('message', (message) => console.log(message.text));
Mawgood.on('error', (error) => console.warn(error.code, error.serverCode));

React props: onOpen, onClose, onMessage, onUnreadChange, onHandoff, onError. Vue events: open, close, message, unreadChange, handoff, error (<MawgoodChat @message="…" />).

An error has a code (network, unauthorized, refused, rate_limited, invalid, bad_response, file_rejected), the HTTP status, and the server's serverCode (for example origin_not_allowed). Network errors and rate limits are retried by the SDK itself.

React Native

Provider props: onOpen, onClose, onMessage, onUnreadChange, onHandoff, onError.

useMawgoodChat() anywhere below the provider:

MemberNotes
open(), close(), toggle()
setUser(identity)Returns a promise.
setPage(page)A screen name ('product') or { screen, title }.
setAttributes(attributes)
logout(), newConversation()Return promises.
registerPushToken(token)Does nothing yet (push comes later).
unread, status, isOpen, state, clientclient is the headless MawgoodChatClient.

Flutter

MawgoodChat.init callbacks: onOpen, onClose, onMessage, onUnreadChange, onHandoff, onError.

Static memberNotes
MawgoodChat.open(context), MawgoodChat.close()
MawgoodChat.setUser(identity)ChatIdentity; returns a Future.
MawgoodChat.setScreen(screen)
MawgoodChat.setAttributes(map)
MawgoodChat.logout()
MawgoodChat.registerPushToken(token)Does nothing yet.
MawgoodChat.client, MawgoodChat.of(context)The headless client, and the controller for a scope.
MawgoodChat.dispose()Tears the bubble down (tests, or switching Mawgoods).

The client's events stream gives ChatSessionReady, ChatMessageReceived, ChatMessageUpdated, ChatTypingChanged, ChatHandoffChanged, ChatLookUpdated, ChatUnreadChanged, ChatConnectionChanged, ChatErrorOccurred, ChatOpened and ChatClosed. It also has send, sendReply, sendFile, sendVoice, loadOlder, catchUp, newConversation, rate, messages, unread, look, status and notice.

When the chat can't work from the app (a key or app the dashboard doesn't allow, the card off, the workspace unavailable), the Flutter client stops (ChatClientStatus.unavailable), the launcher hides, and nothing retries until start() runs again.

On this page