Orello SDK (@orello/sdk)

The official browser SDK for Orello AI. This script mounts a floating launcher, loads the highly interactive widget, and provides a powerful runtime API for site automation and visual context awareness.

✨ Core Features

• Floating Launcher & Widget: Sleek, glassmorphic UI that sits on top of your site.
• Multimodal Context: Automatically captures DOM state and visual screenshots for the AI.
• Voice Transcription: Real-time speech-to-text using Deepgram (with Web Speech API fallback).
• Voice Synthesis: Low-latency text-to-speech using ElevenLabs (with Web Speech Synthesis fallback).
• Wake-Word Support: "Hey [Agent Name]" opens the widget hands-free.
• Programmatic Actions: The AI can click, scroll, and navigate your site autonomously.

🚀 Installation

Embed the Orello agent into any website by adding this script tag before the closing </body> tag:

<script
  src="https://cdn.jsdelivr.net/npm/@orello/sdk@latest/dist/orello.min.js"
  data-api-key="YOUR_WIDGET_KEY"
  data-agent="ASSISTANT_UID"
  data-api-base="https://api.orello.space"
></script>

⚙️ Configuration Attributes

Required

• data-api-key: Your unique Widget API key (found in the Orello Dashboard).
• data-agent: The unique UID of the assistant you want to load.

Optional

• data-api-base: The base URL of the Orello API. Default: https://api.orello.space.
• data-agent-service-url: URL for the real-time interaction socket.
• data-wake-word: Enable the "Hey [Agent Name]" wake-word listener (true or false). Default: true.
• data-session-id: Explicitly set a session ID (useful for cross-page persistence).

🎤 Voice & AI Settings

Users can configure their own provider credentials in the Voice & AI tab of the Orello Settings:

• Deepgram: Used for high-accuracy, real-time transcription. If unavailable, the SDK falls back to the browser's built-in webkitSpeechRecognition.
• ElevenLabs: Used for premium, natural-sounding voice synthesis. If unavailable, the SDK falls back to the browser's built-in window.speechSynthesis.

📡 Emitted Window Events

The SDK dispatches custom events for easy integration:

• orello:ready: Fired when the agent is fully loaded. Access data via event.detail.agent.
• orello:error: Fired on initialization or runtime errors. Access message via event.detail.message.
• orello:navigate: Fired when the AI attempts a soft-navigation. Prevent default to handle it via your router.

🛠️ Runtime API

Programmatic control via window.OrelloWidget:

• open() / close() / toggle(): Control widget visibility.
• actions.click(selector): Force the agent to click an element.
• actions.scroll(x, y): Programmatic scrolling.
• actions.highlight(selector): Pulse an element to guide the user.
• getDom(): Get a sanitized snapshot of the current page DOM.

📄 License

MIT © Orello Team