> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sagepilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK API reference

> Every method on window.ChatWidget and what it returns.

The widget script defines `window.ChatWidget`. Call `init()` once, then wait for the promise it returns before calling other methods. See [Installation](/sdks/web/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](/sdks/web/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](/sdks/web/opening-chat).

## 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](/sdks/web/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](/sdks/web/sending-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`.                                                                                                                 |