Handlers receive one argument, the payload listed below (or nothing). on and once return an unsubscribe function.
Subscribe
JavaScript
const api = window.ASTERLIO_API
api.on('ready', () => console.log('widget ready'))
api.on('capabilities:changed', (caps) => {
helpButton.disabled = !caps.canStartChat && !caps.canSendMessage
})
api.on('message:received', ({ text, staffName }) => {
// text is plain text; content is the agent's HTML — never put it into innerHTML unsanitised
notify(`${staffName ?? 'Support'}: ${text ?? '(attachment)'}`)
})
api.once('conversation:started', ({ chatRoomId }) => track('chat_started', chatRoomId))Lifecycle and view
| Event | Payload | When |
|---|---|---|
ready | — | The widget is mounted and the API can be used. |
view:changed | { view, previous } | The view changed between hidden, button, mini and expanded. |
button:visible | — | Only the launcher button is on screen again. |
widget:shown / widget:hidden | — | show() or hide() ran. |
chat:opened / chat:closed | — | The chat panel opened or closed. |
chat:expanded / chat:minimized | — | The chat switched to the message section, or back to the small panel. |
position:changed | { position, previous, source: 'api' | 'drag' } | The widget moved to another corner. |
What is possible
| Event | Payload | When |
|---|---|---|
capabilities:changed | Capabilities (see Window API) | Something the visitor can or cannot do changed, e.g. the composer became available after the first chat. |
connection:changed | { status: 'connected' | 'connecting' | 'offline' } | The chat connection changed. |
Conversation
| Event | Payload | When |
|---|---|---|
conversation:started | { chatRoomId } | The first-chat form was accepted (by the visitor or setUser silent). |
conversation:rejected | { message, reason, field } | The server rejected the first-chat answers. |
conversation:closed | { chatRoomId } | The team closed the conversation. |
conversation:rated | { rating } | The visitor rated a closed conversation. |
message:sent | { content, fileCount } | The visitor sent a message. |
message:received | { content, text, staffName, fileCount } | A reply arrived in the current conversation. content is the agent's message as HTML (from the CRM editor); text is the same message as plain text. Show text, or sanitise content yourself before rendering it as HTML. Both are null for a file-only message. |
unread:changed | { count } | Unread replies changed (count resets to 0 when the chat opens). |
composer:filled | { queued, fileCount } | openChat() placed a draft in the composer (queued: true when it had been waiting). |
user:set | { mode, fields } | setUser() succeeded. fields lists the answer keys, not the values. |
Session
| Event | Payload | When |
|---|---|---|
session:changed | { sessionId, previous } | The session id changed for any reason. |
session:cleared | { previousSessionId, sessionId } | The session was ended: by clearSession(), by the visitor's Start New Conversation button, or automatically on load when the visitor's stored conversation has since been closed. |
session:restored | { sessionId, chatRoomId } | restoreSession() succeeded. |
Errors
| Event | Payload | When |
|---|---|---|
error | { code, message } | The widget showed an error to the visitor (codes below). |
error codes
The widget shows the message to the visitor itself; the code is there if the host page wants to react.
email_not_recognised— the email submitted on the first-chat form is not registered with the identity provider.verification_unavailable— the identity provider could not be reached, timed out, or rejected the gateway's key. The visitor can retry.chat_first_rejected— the first-chat form was rejected for a reason this widget build does not recognise.FILE_UPLOAD_PENDING— a send was blocked while files were still uploading.INVALID_TYPE,SIZE_EXCEEDED,INVALID_IMAGE_DIMENSIONS,MAX_FILES_EXCEEDED,UPLOAD_ERROR— a file picked by the visitor was rejected or failed to upload.
Raw postMessage events
The widget iframes also post messages to your window. These predate the API above and still work.
Always validate the origin.
JavaScript
const WIDGET_ORIGIN = 'https://DOMAIN'
window.addEventListener('message', (event) => {
if (event.origin !== WIDGET_ORIGIN) return
const { type, payload } = event.data || {}
switch (type) {
case 'HAS_UNREAD_MESSAGES':
// payload: { count }
break
case 'SET_CHAT_ROOM_ID':
// payload: { chatRoomId }
break
case 'SHOW_ERROR_MESSAGE':
// payload: { message, code? }
break
}
})