@cloudcorp/widget

Embeddable voice AI widget. Add real-time voice agents to any website with a single script tag or npm import. Supports React, Vue, Angular, and Svelte.

Install

npm install @cloudcorp/widget

Quick Start

Script Tag (CDN)

<script
  src="https://unpkg.com/@cloudcorp/widget/dist/cloudvoice.js"
  data-agent="your-agent-id"
  data-server="https://your-server.com"
></script>

ES Module

import { Widget } from '@cloudcorp/widget'

const widget = new Widget({
  agent: 'your-agent-id',
  server: 'https://your-server.com',
})

widget.on('transcript', ({ role, text }) => {
  console.log(`${role}: ${text}`)
})

Framework Integration

React

import { CloudVoice, useCloudVoice } from '@cloudcorp/widget/react'

// Component
function App() {
  return (
    <CloudVoice
      agent="your-agent-id"
      server="https://your-server.com"
      onTranscript={({ role, text }) => console.log(`${role}: ${text}`)}
      onReady={({ agentName }) => console.log(`Connected to ${agentName}`)}
    />
  )
}

// Hook
function App() {
  const { ready, sendText, close } = useCloudVoice({
    agent: 'your-agent-id',
    server: 'https://your-server.com',
  })

  return <div>{ready ? 'Connected' : 'Connecting...'}</div>
}

Vue

<script setup>
import { CloudVoice, useCloudVoice } from '@cloudcorp/widget/vue'

// Composable
const { ready, sendText, close } = useCloudVoice({
  agent: 'your-agent-id',
  server: 'https://your-server.com',
})
</script>

<template>
  <!-- Or use the component with events -->
  <CloudVoice
    agent="your-agent-id"
    server="https://your-server.com"
    @transcript="({ role, text }) => console.log(`${role}: ${text}`)"
    @ready="({ agentName }) => console.log(`Connected to ${agentName}`)"
  />
</template>

Angular

import { CloudVoiceDirective } from '@cloudcorp/widget/angular'

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CloudVoiceDirective],
  template: `
    <div
      cloudVoice
      [agent]="'your-agent-id'"
      [server]="'https://your-server.com'"
      (cvTranscript)="onTranscript($event)"
      (cvReady)="onReady($event)"
    ></div>
  `,
})
export class AppComponent {
  onTranscript({ role, text }) {
    console.log(`${role}: ${text}`)
  }
  onReady({ agentName }) {
    console.log(`Connected to ${agentName}`)
  }
}

Svelte

<script>
  import { cloudVoice, createCloudVoice } from '@cloudcorp/widget/svelte'

  // Action
  const params = {
    agent: 'your-agent-id',
    server: 'https://your-server.com',
    onTranscript: ({ role, text }) => console.log(`${role}: ${text}`),
  }

  // Or programmatic
  const { widget, sendText, close } = createCloudVoice({
    agent: 'your-agent-id',
    server: 'https://your-server.com',
  })
</script>

<div use:cloudVoice={params}></div>

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | agent | string | Yes | Agent ID to connect to | | server | string | No | Server URL. Defaults to current page origin | | apiKey | string | No | API key for cross-origin usage | | sessionToken | string | No | One-time session token (alternative to apiKey) | | platform | string | No | Platform identifier. Default: 'widget' | | idleText | string | No | Text shown in idle state | | modes | InteractionMode[] | No | Interaction modes to offer. Default: ['browser'] | | agentPhone | string | No | Phone number for "I'll Call" mode | | whatsappNumber | string | No | WhatsApp number for WhatsApp modes | | requireVerification | 'email' \| 'phone' \| 'both' \| false | No | OTP verification before connecting | | verifyMethod | 'sms' \| 'voice' \| 'whatsapp' | No | How to send verification codes. Default: 'sms' |

Interaction Modes

| Mode | Description | |------|-------------| | browser | Voice conversation directly in the browser | | callMe | Agent calls the user's phone, transcript shows in widget | | illCall | Shows a number to call, transcript shows in widget | | whatsapp | Opens WhatsApp chat, transcript shows in widget | | whatsapp_call | Voice call via WhatsApp number |

<script
  src="https://unpkg.com/@cloudcorp/widget/dist/cloudvoice.js"
  data-agent="your-agent-id"
  data-modes="browser,callMe,whatsapp"
></script>

Events

| Event | Payload | Description | |-------|---------|-------------| | ready | { agentName, version } | Connected to agent | | transcript | { role, text, isFinal } | Speech transcript | | ended | { reason } | Conversation ended | | error | string | Error message | | transfer | { status, reason? } | Human handoff status | | inputRequest | { requestId, fieldName, fieldType, label, ... } | Agent requesting user input |

Methods

| Method | Description | |--------|-------------| | sendText(text) | Send a text message | | close() | End the current session | | destroy() | Remove the widget from the page | | on(event, handler) | Listen for events | | off(event, handler) | Remove event listener |

CDN Data Attributes

All configuration can be set via data-* attributes on the script tag:

<script
  src="https://unpkg.com/@cloudcorp/widget/dist/cloudvoice.js"
  data-agent="your-agent-id"
  data-server="https://your-server.com"
  data-api-key="cv_xxxxx"
  data-modes="browser,callMe,illCall,whatsapp,whatsapp_call"
  data-agent-phone="+1234567890"
  data-whatsapp-number="+1234567890"
  data-require-verification="phone"
  data-verify-method="voice"
  data-idle-text="Hi! How can I help?"
></script>

License

UNLICENSED - proprietary software by CloudCorp