Skip to content
Asterlio

Sessions & Visitors

A session ties a visitor's browser to their conversation.

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

  1. The widget loads and reuses the stored session, or creates a new one.
  2. The visitor completes the first-chat form (or you call setUser(…, { mode: 'silent' })). The server opens a conversation and conversation:started fires with its chatRoomId.
  3. Messages flow until the team closes the conversation (conversation:closed).
  4. The visitor presses Start New Conversation, or you call clearSession(): the session ends and a new one starts (session:cleared).
  5. 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:cleared fires).

Reading the session

JavaScript
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.

JavaScript
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 with session_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.
JavaScript
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.
JavaScript
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.

Was this page helpful?