@cloudcorp/widget

@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