Use it to position, show and hide the widget, open the chat, place a message in the composer, identify the visitor, manage sessions and listen for events.
How calls behave
- Actions return a
Promise. They wait until the widget is ready, so you can call them straight after the script loads. - A rejected promise always carries
{ code, message, details? }. See error codes. - Getters (
getView,getSessionId, …) are synchronous.
In the dashboard preview (demo mode) actions reject with demo_mode.
Interface
type Corner = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
type View = 'hidden' | 'button' | 'mini' | 'expanded'
interface ASTERLIO_API {
// lifecycle
init(clientId: string): Promise<void>
ready(): Promise<void>
isReady(): boolean
on(event: string, handler: (data) => void): () => void // returns unsubscribe
once(event: string, handler: (data) => void): () => void
off(event: string, handler: (data) => void): void
destroy(): void
onReady?: () => void // optional; set it before the loader runs
// visibility and view
show(): Promise<void>
hide(): Promise<void>
isVisible(): boolean
open(): Promise<void>
close(): Promise<void>
toggle(): Promise<void>
expand(): Promise<void>
minimize(): Promise<void>
getView(): View
// position
setPosition(corner: Corner, options?: { persist?: boolean }): Promise<void>
getPosition(): Corner
// composer, capabilities, first chat, visitor
openChat(options?: { message?: string; files?: File[] | FileList; queue?: boolean })
: Promise<{ queued: boolean; fileCount: number }>
getCapabilities(): Capabilities
getFirstChatFields(): FirstChatField[]
setUser(values: Record<string, string>, options?: { mode?: 'prefill' | 'silent' })
: Promise<{ mode: 'prefill' | 'silent'; chatRoomId?: string }>
// session
getSessionId(): string | null
getChatRoomId(): string | null
clearSession(): Promise<{ sessionId: string; chatRoomId: null }>
restoreSession(sessionId: string): Promise<{ sessionId: string; chatRoomId: string }>
// state
getState(): {
ready: boolean; view: View; isVisible: boolean; isChatOpen: boolean; isExpanded: boolean
position: Corner; sessionId: string | null; chatRoomId: string | null
unreadCount: number; capabilities: Capabilities
}
config: { domain: string; version: string }
}Lifecycle
ready()
Resolves once the widget is mounted and the chat can take API calls. Rejects with not_ready if the widget failed to load or the client is inactive.
Rejects with: not_ready, demo_mode
await window.ASTERLIO_API.ready()
console.log(window.ASTERLIO_API.getState())onReady (callback property)
Before the loader runs, ASTERLIO_API is the empty object from the embed snippet, so its methods do not exist yet. Set onReady in the snippet to run code as soon as the widget is ready.
var ASTERLIO_API = ASTERLIO_API || {}, ASTERLIO_LoadStart = new Date();
ASTERLIO_API.onReady = function () {
ASTERLIO_API.setPosition('bottom-left', { persist: false })
}on(event, handler) / once(event, handler) / off(event, handler)
Subscribe to widget events. on and once return an unsubscribe function. A handler that throws is logged and does not affect the widget.
const stop = window.ASTERLIO_API.on('view:changed', ({ view, previous }) => {
console.log('view', previous, '→', view)
})
// later
stop()destroy()
Removes the widget from the page and detaches its listeners. Pending calls reject with not_ready. Listeners added with on() are kept, so calling init() again reports to them.
Visibility and view
The view is one of: hidden (nothing on screen), button (launcher only), mini (small welcome panel) or expanded (message section or first-chat form).
show() / hide()
Animate the whole widget in or out (about 0.5 s). hide() closes the chat first. The promise resolves when the animation has finished.
// hide on checkout pages
if (location.pathname.startsWith('/checkout')) window.ASTERLIO_API.hide()open() / close() / toggle()
Open the chat panel from the launcher button, or close it back to the button. open() shows the widget first if it was hidden. A visitor who already started a chat sees the expanded view.
expand() / minimize()
Switch between the small welcome panel and the larger message section. expand() opens the chat if needed. When no conversation exists yet, the expanded view shows the first-chat form.
Rejects with: connecting (the chat stayed busy for 5 s), demo_mode
getView() / isVisible()
Read the current view and whether the widget is shown.
Position
setPosition(corner, { persist = true })
Move the widget to one of the four corners. When only the launcher is on screen it pops out and back in at the new corner. With persist: true the corner is remembered for this visitor, as when they drag the button; visitors can still drag it afterwards.
Rejects with: invalid_argument
window.ASTERLIO_API.setPosition('top-left', { persist: false })getPosition()
Returns the current corner.
Opening the chat with a message or files
openChat({ message, files, queue })
Opens the message section and places the message and/or files in the composer, then focuses it. Nothing is sent: the visitor reviews and presses send. The message replaces any text already in the composer. Files are checked against the same rules as the file picker (png, jpg, jpeg, gif or pdf; up to 5 MB each; at most 3 per message) and start uploading straight away. Before the visitor has completed the first-chat form there is no composer: the chat is left open at the form and the call rejects with first_chat_required, unless you pass queue: true, in which case the draft is held and placed as soon as the conversation starts.
Rejects with: first_chat_required, conversation_closed, outside_working_hours, invalid_file, too_many_files, invalid_argument, connecting
const input = document.querySelector('#attachment')
try {
const { queued } = await window.ASTERLIO_API.openChat({
message: 'Hi, I have a question about order 1042',
files: input.files,
queue: true,
})
if (queued) console.log('Draft will appear once the visitor starts the chat')
} catch (error) {
console.warn(error.code, error.message, error.details)
}getCapabilities()
Tells you what is possible right now, and why not when something is blocked. The same object is sent with the capabilities:changed event whenever it changes.
const caps = window.ASTERLIO_API.getCapabilities()
if (!caps.canSendMessage) console.log('blocked by', caps.blockedReason)First chat and the visitor
getFirstChatFields()
Lists the questions on the client's first-chat form, with the kind of each answer and the options for select fields. Every listed field is required.
window.ASTERLIO_API.getFirstChatFields()
// [{ key: '2', fieldName: 'email', label: 'What is your email?', kind: 'email', required: true }, …]setUser(values, { mode = 'prefill' })
Identifies the visitor. Key values by fieldName (or key). mode 'prefill' opens the chat at the first-chat form with the answers filled in for the visitor to confirm; partial answers are fine. mode 'silent' validates the complete answers with the form's rules and starts the conversation in the background without opening the widget; it resolves with the new chatRoomId once the server accepts it. Only one conversation can be active, so call clearSession() first to start over.
Rejects with: conversation_active, outside_working_hours, invalid_user_data, connecting, timeout, invalid_argument
// signed-in visitor: start the conversation without showing the form
await window.ASTERLIO_API.setUser(
{ email: 'jane.doe@example.com', phone: '+447700900123', ticket_category: 'Billing' },
{ mode: 'silent' },
)Sessions
See the Sessions page for the session lifecycle and what can and cannot be restored.
getSessionId() / getChatRoomId()
Return the current session id and conversation (chat room) id, or null.
clearSession()
Ends the current session (as the visitor's Start New Conversation button does), starts a fresh one and returns its id. The ended session can no longer be restored from this browser.
Rejects with: failed, demo_mode
restoreSession(sessionId)
Switches the widget to an earlier session and rejoins its conversation. A session with no conversation is refused with session_not_found; this includes a conversation the team has closed, because the server no longer returns its history. If the server reports the conversation as closed while rejoining, or it cannot be rejoined in time, the widget goes back to the session it was on and the call rejects. In every failure case the widget stays on its current session.
Rejects with: invalid_session_id, session_retired, session_not_found, session_closed, timeout
try {
await window.ASTERLIO_API.restoreSession(savedSessionId)
} catch (error) {
if (['session_closed', 'session_not_found', 'session_retired'].includes(error.code)) {
forgetSavedSession() // it cannot be continued; the visitor starts a new chat
}
}State
getState()
Returns a snapshot: ready, view, isVisible, isChatOpen, isExpanded, position, sessionId, chatRoomId, unreadCount and capabilities.
Error codes
| Code | Meaning |
|---|---|
not_ready | the widget failed to load, is inactive, or was destroyed |
demo_mode | called inside the dashboard preview |
timeout | the widget or server did not answer in time |
invalid_argument | a parameter has the wrong type or value |
first_chat_required | no conversation yet; the visitor must complete the first-chat form |
conversation_closed | the current conversation was closed by the team |
outside_working_hours | the team is not available right now |
connecting | the chat is still connecting; try again shortly |
invalid_file | a file has the wrong type, size or dimensions (see details) |
too_many_files | more than 3 files on one message |
invalid_user_data | setUser answers are missing, invalid or unknown, or the server rejected them (see details) |
conversation_active | setUser was called while a conversation is in progress |
invalid_session_id | the id is not a session id for this widget |
session_retired | this browser ended that session |
session_not_found | that session has no conversation to restore (including one the team has closed) |
session_closed | the server reported the conversation as closed while the widget rejoined it |
failed | anything else; message explains |
Advanced (low level)
These post raw messages into the widget iframes.
Prefer the methods above; the raw message format may change.
// post a raw message to the button / chat / CTA iframe
window.ASTERLIO_API.sendToButton?.({ type: 'UPDATE_STATE', payload: { isChatOpen: true } })
window.ASTERLIO_API.sendToChat?.({ type: 'WIDGET_MINIMIZE' })
window.ASTERLIO_API.sendToCta?.({ type: 'BUTTON_HOVER_OPEN' })
// read widget build metadata
console.log(window.ASTERLIO_API.config) // { domain, version }