@moveo-ai/web-client
Version:
Client side library to load the moveo chat widget and connect it with your agent
240 lines (172 loc) • 6.19 kB
Markdown
# @moveo-ai/web-client
[](https://www.npmjs.com/package/@moveo-ai/web-client)
[](https://www.npmjs.com/package/@moveo-ai/web-client)
[](https://opensource.org/licenses/MIT)
Embeddable chat widget for integrating [Moveo.ai](https://moveo.ai) AI Agents into your website or application.
## Features
- Real-time chat with AI Agents
- Customizable appearance and theming
- Multi-language support (22 languages)
- File upload and media sharing
- Mobile-responsive design
- Secure iframe-based isolation
## Table of Contents
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [TypeScript Support](#typescript-support)
- [Browser Support](#browser-support)
- [Local Development](#local-development)
- [License](#license)
## Quick Start
1. Create an account at [console.moveo.ai](https://console.moveo.ai)
2. Create an environment and web integration
3. Copy your integration ID
4. Add the widget to your website using one of the methods below
## Installation
### CDN (Recommended for most websites)
Add the script tag to your HTML:
```html
<script src="https://web.moveo.ai/web-client.min.js"></script>
<script>
MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' });
</script>
```
### npm (For module bundlers)
```bash
npm install @moveo-ai/web-client
```
```typescript
import MoveoAI from '@moveo-ai/web-client';
MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' });
```
**Requirements:** Node.js 18+
## Usage
### Basic
```html
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<!-- Your website content -->
<script src="https://web.moveo.ai/web-client.min.js"></script>
<script>
window.addEventListener('load', function () {
MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' });
});
</script>
</body>
</html>
```
### With Configuration Options
```javascript
MoveoAI.init({
integrationId: 'YOUR_INTEGRATION_ID',
context: {
user_id: 'user-123',
user_name: 'John Doe',
user_email: 'john@example.com',
},
language: 'en',
});
```
### Programmatic Control
```javascript
const controller = MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' });
// Open the chat widget
controller.open();
// Close the chat widget
controller.close();
// Toggle the widget
controller.toggle();
// Send a message programmatically
controller.sendMessage('Hello!');
// Update context
controller.updateContext({ user_id: 'new-user-456' });
// Destroy the widget
controller.destroy();
```
## API Reference
### MoveoAI.init(config)
Initializes the chat widget.
| Parameter | Type | Required | Description |
| --------------- | -------- | -------- | ----------------------------------------- |
| `integrationId` | `string` | Yes | Your Moveo.ai integration ID |
| `context` | `object` | No | Custom context variables for the AI Agent |
| `language` | `string` | No | Widget language (ISO 639-1 code) |
**Returns:** `WidgetController` - Controller instance for programmatic control
### WidgetController Methods
| Method | Description |
| ---------------------------- | -------------------------------- |
| `open()` | Opens the chat widget |
| `close()` | Closes the chat widget |
| `toggle()` | Toggles the widget open/closed |
| `sendMessage(text: string)` | Sends a message to the agent |
| `updateContext(ctx: object)` | Updates the conversation context |
| `destroy()` | Removes the widget from the page |
## Configuration
### Context Variables
Pass custom data to your AI Agent:
```javascript
MoveoAI.init({
integrationId: 'YOUR_INTEGRATION_ID',
context: {
// User information
user_id: 'user-123',
user_name: 'John Doe',
user_email: 'john@example.com',
// Custom business data
subscription_tier: 'premium',
account_balance: 150.0,
// Any custom key-value pairs
custom_field: 'custom_value',
},
});
```
### Supported Languages
The widget supports 22 languages including: English, Spanish, French, German, Italian, Portuguese, Dutch, Greek, Arabic, Hebrew, and more.
```javascript
MoveoAI.init({
integrationId: 'YOUR_INTEGRATION_ID',
language: 'es', // Spanish
});
```
## TypeScript Support
Full TypeScript definitions are included:
```typescript
import MoveoAI, { WidgetController, WidgetConfig } from '@moveo-ai/web-client';
const config: WidgetConfig = {
integrationId: 'YOUR_INTEGRATION_ID',
context: {
user_id: 'user-123',
},
};
const controller: WidgetController = MoveoAI.init(config);
```
## Browser Support
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Android Chrome)
## Local Development
### HTTPS Setup
The dev server runs on HTTPS. To avoid browser security warnings, generate locally-trusted certificates:
```bash
npm run setup:certs
```
This generates certificates in `.certs/` and attempts to install the CA into your system trust store (requires `sudo` on macOS/Linux). Restart your browser after running.
> **Firefox users:** Go to `about:preferences#privacy` → Certificates → View Certificates → Authorities → Import, and add `.certs/ca.crt`.
If the CA was not auto-installed, run the platform command printed by the script to add it manually.
## Support
- Documentation: [docs.moveo.ai](https://docs.moveo.ai)
- Console: [console.moveo.ai](https://console.moveo.ai)
- Website: [moveo.ai](https://moveo.ai)
## License
MIT License - see [LICENSE](LICENSE) for details.