window.ChatWidget. Call init() once, then wait for the promise it returns before calling other methods. See Installation. The optional @sagepilot-ai/web-push-addon has a separate lifecycle documented below.
Methods
Setup
init(config)
Loads the channel and adds the launcher and chat to the page. Resolves when the widget is ready to use. See Configuration for every option.
- Call it once per page. Later calls are ignored and log a warning.
- If
keyis missing or not in the formatworkspace_id:channel_id, it logs an error and resolves without loading the widget.open()then returnsfalse. - If the channel cannot be loaded, the promise rejects.
Opening and closing
open()
Opens the chat. Returns true if the chat is open, including when it was already open. Returns false if the widget is not ready. Skips the welcome popup and the two-step intro card.
close()
Closes the chat. Returns true, or false if the widget is not ready.
toggle()
Opens the chat if it is closed, and closes it if it is open. Returns true when it opened the chat and false when it closed it. Call it only after the widget is ready.
isOpen()
Returns true if the chat is currently open.
See Open chat from your own button.
Identity
identify(identity)
Links the visitor to a customer. Accepts user_id (required), email, name, phone, custom_properties, and user_hash. Resolves to { success: true, customer } or { success: false, error }. Never rejects.
logout()
Clears the customer identity from the widget and this browser. The chat resets to an anonymous session.
getIdentityState()
Returns identified, pending, and customer synchronously.
onIdentify(callback)
Calls callback immediately if the visitor is already identified, or when an in-progress identify() succeeds. Does nothing otherwise.
See Identity.
Messages
setDraft(text)
Puts text in the chat’s message box without sending it. Resolves to a result with status drafted, failed, or requires_input.
sendMessage(text)
Sends text as the visitor. Resolves to a result with status sent, requires_input, failed, or unknown. Never retry automatically.
See Draft and send messages for every status and code.
Timing
Web Push add-on
Install and import the optional browser Push API separately from the widget script:Constructor
Capability and lifecycle methods
subscribe() accepts one optional consent field:
marketingConsent only when the customer’s action explicitly disclosed marketing notifications. Omitting it leaves the existing marketing preference unchanged.
Use stable, non-token customer IDs of 1–45 characters for new integrations. Existing longer IDs are lookup-only. Include backend-verified contacts for new identified customers; an ID-only proof can resolve a contactless customer and be rejected by the anonymous-push policy. See the proof contract.
The exchanged Push authorization lasts 24 hours. Call identify() with a fresh backend proof to renew it before expiry; the add-on does not fetch proofs for you. Stop renewal before logout or account changes.
Registration result
subscribe() and sync() return:
registered does not mean marketing consent is enabled or that a notification was delivered.
Preferences
Supported preference keys areenabled, marketing_enabled and support_enabled at the global level or under web and app overrides:
enabled: false blocks all Push; web.enabled: false blocks Web Push. A web category override takes precedence over the matching global category. New SDK customers default to marketing disabled. Read the effective preferences before showing an enabled state; subscribe({ marketingConsent: true }) does not override a global opt-out. These settings apply to the customer’s devices in the selected scope.
Errors
Operational failures are instances ofSagepilotWebPushError:
Endpoint registration automatically retries transient network errors,
408, 429 and 5xx responses with bounded delays. Explicit opt-out, logout and customer-account changes are never retried as a new subscription without customer intent.