The widget creates one the first time it loads and keeps it in the browser's storage, so a returning visitor sees their chat.
Lifecycle
- The widget loads and reuses the stored session, or creates a new one.
- The visitor completes the first-chat form (or you call
setUser(…, { mode: 'silent' })). The server opens a conversation andconversation:startedfires with itschatRoomId. - Messages flow until the team closes the conversation (
conversation:closed). - The visitor presses Start New Conversation, or you call
clearSession(): the session ends and a new one starts (session:cleared). - If the visitor comes back after the team closed their conversation, the widget does the same on load: it ends the old session, starts a new one and shows the first-chat form (
session:clearedfires).
Reading the session
const api = window.ASTERLIO_API
await api.ready()
api.getSessionId() // 'client_<clientId>_sess_<token>_<token>'
api.getChatRoomId() // null until the first chat is accepted
api.on('session:changed', ({ sessionId, previous }) => saveForAccount(sessionId))Ending a session
clearSession() clears the conversation from the widget, starts a new session and resolves with its id. Use it when a signed-in visitor signs out, so the next person on the same browser does not see their chat.
async function onSignOut() {
const { sessionId } = await window.ASTERLIO_API.clearSession()
console.log('fresh session', sessionId)
}Restoring a session
restoreSession(id) switches the widget to an earlier session and rejoins its conversation, for example to continue a chat on another device after the visitor signs in.
- The id must be a session id for this widget's client (
invalid_session_id). - A session that was ended in this browser, by Start New Conversation or
clearSession(), cannot be restored here (session_retired). This list is kept in the browser's storage, so it does not follow the visitor to other devices. - A session without a conversation cannot be restored (
session_not_found). Once the team closes a conversation the server no longer returns its history, so a closed conversation is also refused withsession_not_found. - If the server reports the conversation as closed while the widget rejoins it, the widget goes back to the session it was on and the call rejects with
session_closed. That session is then also refused in this browser. - Either way the widget stays on the session it was on.
async function onSignIn(account) {
if (!account.chatSessionId) return
try {
await window.ASTERLIO_API.restoreSession(account.chatSessionId)
} catch (error) {
// session_closed, session_retired, session_not_found, …
if (error.code !== 'timeout') await forgetChatSession(account)
}
}Identifying the visitor
getFirstChatFields() lists the client's first-chat questions. Pass answers keyed by fieldName to setUser:
mode: 'prefill'(default) opens the form with the answers filled in. The visitor checks them and presses Start Chat.mode: 'silent'checks the answers with the same rules as the form and starts the conversation without opening the widget. All fields are required.
const fields = window.ASTERLIO_API.getFirstChatFields()
// [{ fieldName: 'email', kind: 'email', … }, { fieldName: 'ticket_category', kind: 'select', options: […] }]
try {
await window.ASTERLIO_API.setUser(
{ email: user.email, phone: user.phone, ticket_category: 'Billing' },
{ mode: 'silent' },
)
} catch (error) {
if (error.code === 'invalid_user_data') {
// fall back to the form so the visitor can fix the answers
await window.ASTERLIO_API.setUser({ email: user.email }, { mode: 'prefill' })
}
}Treat session ids as secrets
The widget loads a conversation using nothing but its session id, so treat the id like a password. Store ids only server-side or against the signed-in account, never in URLs, analytics or logs, and only restore a session for the visitor it belongs to.