npm package: @lemonsliceai/lemon-slice-widget
Description: The LemonSlice widget
Author: LemonSlice AI
Latest version: 1.0.29

# LemonSlice Agent Widget

LemonSlice Agent Widget is an embeddable web component that enables real-time video chat with LemonSlice AI agents. It provides a floating or inline widget that connects users to LemonSlice AI agents via video and audio. The widget is distributed as an npm package and can be embedded in any webpage with a single HTML tag.

LemonSlice agents are created on [https://lemonslice.com/](https://lemonslice.com/)

## How to use it
``` html
<lemon-slice-widget agent-id="agent_id"></lemon-slice-widget>
<script type="module" src="https://unpkg.com/@lemonsliceai/lemon-slice-widget"></script>
```

## Configuration

### Attributes

- **`agent-id`** (required): Your LemonSlice agent ID
- **`inline`**: Display widget inline instead of floating (default: `false`)
- **`show-minimize-button`**: Show/hide the minimize button (default: `true`)
- **`initial-state`**: Initial widget state on load - `"minimized"`, `"active"`, or `"hidden"` (default: `"minimized"`)
- **`controlled-widget-state`**: Dynamically control widget state - `"minimized"`, `"active"`, or `"hidden"`
- **`controlled-show-minimize-button`**: Dynamically control minimize button visibility - `"true"` or `"false"`
- **`custom-active-width`**: Custom width for the active widget state in pixels (default: `320`)
- **`custom-active-height`**: Custom height for the active widget state in pixels (default: `480`)
- **`custom-minimized-width`**: Custom width for the minimized widget state in pixels 
- **`custom-minimized-height`**: Custom height for the minimized widget state in pixels 
- **`video-button-color-hex`**: Hex color (with or without `#`) used for the minimized video chat button (default: `#919191`)
- **`video-button-color-opacity`**: Opacity for the video chat button color in the range `[0, 1]` (default: `0.3`)
- **`video-button-text`**: Custom text to display on the video button. If not provided, defaults to "Video chat" on desktop and "Join" on mobile
- **`hide-powered-by`**: Hide the "Powered by Lemon Slice" branding (default: `false`)
- **`hide-ui`**: Hide all UI elements and use programmatic API only (default: `false`)

### Examples

```html
<!-- Start expanded -->
<lemon-slice-widget agent-id="agent_id" initial-state="active"></lemon-slice-widget>

<!-- Hide minimize button -->
<lemon-slice-widget agent-id="agent_id" show-minimize-button="false"></lemon-slice-widget>

<!-- Inline widget -->
<lemon-slice-widget agent-id="agent_id" inline></lemon-slice-widget>

<!-- Custom button color -->
<lemon-slice-widget
  agent-id="agent_id"
  video-button-color-hex="#FF4FD8"
  video-button-color-opacity="0.8"
></lemon-slice-widget>

<!-- Custom button text -->
<lemon-slice-widget
  agent-id="agent_id"
  video-button-text="Start Chat"
></lemon-slice-widget>

<!-- Custom widget sizes -->
<lemon-slice-widget
  agent-id="agent_id"
  custom-active-width="400"
  custom-active-height="600"
  custom-minimized-width="80"
  custom-minimized-height="80"
></lemon-slice-widget>

<!-- Hide powered by branding -->
<lemon-slice-widget agent-id="agent_id" hide-powered-by></lemon-slice-widget>

<!-- Hide UI and use programmatic API only -->
<lemon-slice-widget agent-id="agent_id" hide-ui></lemon-slice-widget>

```
To programmatically disable the UI you must remove the attribute rather than set it to the string "false".

### Dynamic Control

Control the widget dynamically by updating attributes:

```javascript
const widget = document.querySelector('lemon-slice-widget');

// Change widget state
widget.setAttribute('controlled-widget-state', 'active');

// Toggle minimize button
widget.setAttribute('controlled-show-minimize-button', 'false');
```

## Programmatic API

When the `hide-ui` attribute is set, all UI elements are hidden and you can control the widget programmatically. The widget exposes the following methods on the custom element:

### Audio Control (Speaker)

- **`mute()`**: Mute the speaker/audio output (returns `Promise<void>`)
- **`unmute()`**: Unmute the speaker/audio output (returns `Promise<void>`)
- **`isMuted()`**: Check if audio is currently muted (returns `boolean`)
- **`canUnmute()`**: Check if audio can be unmuted (returns `boolean`)

### Microphone Control

- **`micOn()`**: Turn on the microphone. This will automatically start the room if not already started (returns `Promise<void>`)
- **`micOff()`**: Turn off the microphone (returns `Promise<void>`)
- **`isMicOn()`**: Check if microphone is currently on (returns `boolean`). Currently always returns true. 
- **`canTurnOnMic()`**: Check if microphone can be turned on (returns `boolean`) Currently always returns true. 

### Message Sending

- **`sendMessage(message: string)`**: Send a message to the agent. This will automatically start the room if not already started (returns `Promise<void>`)

### Notes

- `micOn()` and `sendMessage()` will automatically:
  - Set user interaction flag
  - Ensure widget is in active state
  - Create a room if one doesn't exist
  - Join the room if not already joined

### Example Usage

```javascript
const widget = document.querySelector('lemon-slice-widget');

// Hide UI and use programmatic control
widget.setAttribute('hide-ui', 'true');

// Turn on microphone (will start room automatically)
await widget.micOn();

// Send a message (will start room automatically if needed)
await widget.sendMessage('Hello, agent!');

// Check microphone status
if (widget.isMicOn()) {
  console.log('Microphone is on');
}

// Mute audio
await widget.mute();

// Check if muted
if (widget.isMuted()) {
  console.log('Audio is muted');
}
```