# SDK reference (/docs/developers/sdk-reference)

The SDK is published on npm as [`@skavelo/sdk`](https://www.npmjs.com/package/@skavelo/sdk).

```bash
npm install @skavelo/sdk
```

```ts
import { Skavelo } from '@skavelo/sdk';

const skavelo = Skavelo.init({
  agentId: 'YOUR_AGENT_ID',
  user: { id: currentUser.id, plan: currentUser.plan },
  theme: { position: 'bottom-right' },
});
```

With the script tag, the same API is available as `window.Skavelo`.

## Skavelo.init(options) [#skaveloinitoptions]

Starts the widget and returns it. Calling `init` again with the same ID returns the same widget, so it's safe in code that runs more than once. During server rendering it returns a stand-in that does nothing.

| Option | Type | Description |
| --- | --- | --- |
| `agentId` | `string` | The agent to show everywhere. Found on the agent's Install tab. |
| `workspaceId` | `string` | Instead of `agentId`: show each page the agent whose Targeting matches it. See [Multiple agents](/docs/installing/multiple-agents). |
| `user` | `object` | Who's signed in. The same fields as [`identify`](/docs/installing/identify-users). |
| `theme` | `object` | Appearance settings that override the dashboard; see below. |
| `actions` | `object` | How [skills](/docs/skills) call your app; see below. |
| `diagnostics` | `object` | `{ network: false }` stops the widget noting your app's failed requests. On by default. See [What the widget sends](/docs/security-and-privacy/what-the-widget-sends#failed-requests). |

### theme [#theme]

| Field | Description |
| --- | --- |
| `accent` | Accent color, as a hex value such as `#2F6BFF` |
| `background`, `text` | Panel background and text colors. Leave unset to follow the visitor's light or dark mode. |
| `title` | The chat panel's title |
| `label` | The launcher's text |
| `icon` | An image URL used in place of the Skavelo mark |
| `position` | `'bottom-center'`, `'bottom-right'` or `'bottom-left'` |
| `offset` | Distance from the edge of the screen, in pixels. Default 24. |
| `highlight` | `'beacon'`, `'spotlight'`, `'trace'` or `'ring'`. See [Highlight styles](/docs/customizing/highlight-styles). |

### actions [#actions]

| Field | Description |
| --- | --- |
| `headers` | A function returning extra headers for lookups and actions, such as a CSRF token or a bearer token. Called right before each request. |
| `baseUrl` | Where your API lives, if it isn't on the same site as the page |

Cookies are always included in these requests, so lookups and actions run as the signed-in user.

## Methods [#methods]

| Method | Description |
| --- | --- |
| `identify(user)` | Sets or updates the signed-in user. See [Identify signed-in users](/docs/installing/identify-users). |
| `open()` | Opens the widget |
| `close()` | Closes the widget |
| `ask(question)` | Opens the widget and asks a question for the user, for example from a help button in your app |
| `startWorkflow(id, { intro })` | Plays one of the agent's walkthroughs by its id from the Product map. It doesn't ask the AI and doesn't count as a conversation. An introduction with the walkthrough's name and a **Start** button comes first; pass `{ intro: false }` to start straight away, for example from your own "Show me how" button |
| `event(name)` | Tells Skavelo something the user just did, like `event('project_created')`, so a [walkthrough offer](/docs/walkthroughs/walkthrough-offers) set for that event can show. Nothing is sent or stored |
| `on(event, handler)` | Listens for a [widget event](/docs/developers/events) |
| `off(event, handler)` | Stops listening |
| `destroy()` | Removes the widget from the page |

## Marking sensitive content [#marking-sensitive-content]

The widget never sends what users type into fields. To keep other parts of a page private too, such as account numbers shown on screen, add `data-sk-sensitive` to the element. Skavelo skips everything inside it.

```html
<section data-sk-sensitive>
  Card ending 4242
</section>
```