SDK reference
Options, methods and theme settings for the Skavelo SDK.
The SDK is published on npm as @skavelo/sdk.
npm install @skavelo/sdkimport { 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)
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. |
user | object | Who's signed in. The same fields as identify. |
theme | object | Appearance settings that override the dashboard; see below. |
actions | object | How 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. |
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. |
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
| Method | Description |
|---|---|
identify(user) | Sets or updates the signed-in user. See Identify signed-in 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 set for that event can show. Nothing is sent or stored |
on(event, handler) | Listens for a widget event |
off(event, handler) | Stops listening |
destroy() | Removes the widget from the page |
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.
<section data-sk-sensitive>
Card ending 4242
</section>