Skip to content
Asterlio

Events

Subscribe with window.ASTERLIO_API.on(event, handler).

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

EventPayloadWhen
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

EventPayloadWhen
capabilities:changedCapabilities (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

EventPayloadWhen
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

EventPayloadWhen
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

EventPayloadWhen
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
  }
})

Was this page helpful?