Web SDK API reference - Sagepilot Docs

The widget script defines window.ChatWidget. Call init() once, then wait for the promise it returns before calling other methods. See Installation.

Methods

Method	Returns
`ChatWidget.init(config)`	`Promise<void>`
`ChatWidget.open()`	`boolean`
`ChatWidget.close()`	`boolean`
`ChatWidget.toggle()`	`boolean`
`ChatWidget.isOpen()`	`boolean`
`ChatWidget.identify(identity)`	`Promise<IdentifyResult>`
`ChatWidget.logout()`	`void`
`ChatWidget.getIdentityState()`	`{ identified, pending, customer }`
`ChatWidget.onIdentify(callback)`	`void`
`ChatWidget.setDraft(text)`	`Promise<CommandResult>`
`ChatWidget.sendMessage(text)`	`Promise<CommandResult>`

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 key is missing or not in the format workspace_id:channel_id, it logs an error and resolves without loading the widget. open() then returns false.
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

Situation	Behavior
Called before `init()` finishes	`open()`, `close()`, and `toggle()` do nothing, and `open()` and `close()` return `false`. `setDraft()` and `sendMessage()` resolve with `not_initialized`. Calls are not queued.
Chat not ready after 15 seconds	`setDraft()` and `sendMessage()` resolve with `not_ready`.
No result 60 seconds after sending	`sendMessage()` resolves with `unknown` and code `timeout`.
`identify()` or `logout()` in progress	`setDraft()` and `sendMessage()` resolve with `identity_pending`.

​Methods

​Setup

​init(config)

​Opening and closing

​open()

​close()

​toggle()

​isOpen()

​Identity

​identify(identity)

​logout()

​getIdentityState()

​onIdentify(callback)

​Messages

​setDraft(text)

​sendMessage(text)

​Timing