use-arbol-assistant

A simple React hook for integrating real-time AI voice conversations using OpenAI's Realtime API with Arbol's platform.

Features

• 🎤 Real-time voice conversations with OpenAI's latest Realtime API
• 🔊 Audio streaming via WebRTC for low latency
• 📝 Automatic transcription of both user and assistant speech
• ⚡ Ultra-simple API - just one function call
• 🛡️ TypeScript first with full type safety
• 🚀 Easy integration with existing React applications

Installation

npm install use-arbol-assistant

yarn add use-arbol-assistant

pnpm add use-arbol-assistant

bun add use-arbol-assistant

Quick Start

import { useArbolAssistant } from 'use-arbol-assistant'

function VoiceAssistant() {
  const { isLoading, isActiveSession, error, toggleSession } = useArbolAssistant('your-tenant-id')

  return (
    <div>
      {error && <div className="mb-2 rounded bg-red-100 p-2 text-red-700">Error: {error}</div>}

      <button onClick={toggleSession} disabled={isLoading}>
        {isLoading ? 'Connecting...' : isActiveSession ? 'Stop Conversation' : 'Start Conversation'}
      </button>

      {isActiveSession && (
        <div className="flex items-center gap-2">
          <div className="h-2 w-2 animate-pulse rounded-full bg-green-500" />
          <span>Conversation active</span>
        </div>
      )}
    </div>
  )
}

API Reference

useArbolAssistant(tenantId)

Parameters

• tenantId (string): Your Arbol tenant ID

Returns (UseArbolAssistantReturn)

• isLoading (boolean): Whether the session is being established
• isActiveSession (boolean): Whether a conversation is currently active
• error (string | null): Current error message, if any (e.g., "Tenant not found", "Failed to create session")
• toggleSession (() => Promise<void>): Start or stop the conversation

That's it! Super simple. 🎉

Examples

Basic Usage

import { useArbolAssistant } from 'use-arbol-assistant'

function App() {
  const { isLoading, isActiveSession, error, toggleSession } = useArbolAssistant('my-tenant-id')

  return (
    <div className="p-4">
      <h1>AI Voice Assistant</h1>

      {error && (
        <div className="mb-4 rounded bg-red-100 p-3 text-red-700">
          <strong>Error:</strong> {error}
        </div>
      )}

      <button
        onClick={toggleSession}
        disabled={isLoading}
        className={`rounded px-4 py-2 ${isActiveSession ? 'bg-red-500 text-white' : 'bg-blue-500 text-white'}`}
      >
        {isLoading && 'Connecting...'}
        {!isLoading && isActiveSession && 'End Conversation'}
        {!isLoading && !isActiveSession && 'Start Conversation'}
      </button>
    </div>
  )
}

Sidebar Integration

Perfect for navigation bars or sidebars:

import { useArbolAssistant } from 'use-arbol-assistant'
import { MicrophoneIcon, ExclamationTriangleIcon } from '@heroicons/react/16/solid'

function SidebarConversation({ tenantId }: { tenantId: string }) {
  const { isLoading, isActiveSession, error, toggleSession } = useArbolAssistant(tenantId)
  const [isHovering, setIsHovering] = useState(false)

  const getLabel = () => {
    if (error) {
      return isHovering ? 'Retry connection' : 'Connection failed'
    }

    if (isLoading && !isActiveSession) {
      return 'Connecting...'
    }

    if (isActiveSession && !isLoading) {
      return isHovering ? 'Stop conversation' : 'Ongoing conversation'
    }

    return 'Start conversation'
  }

  const getIcon = () => {
    if (error) {
      return <ExclamationTriangleIcon className="text-red-500" />
    }
    return <MicrophoneIcon />
  }

  const getStatusIndicator = () => {
    if (error) {
      return (
        <div className="ml-auto">
          <div className="h-2 w-2 rounded-full bg-red-500" />
        </div>
      )
    }

    if (isActiveSession) {
      return (
        <div className="ml-auto">
          <div className="h-2 w-2 animate-pulse rounded-full bg-green-500" />
        </div>
      )
    }

    return null
  }

  return (
    <SidebarItem
      onClick={toggleSession}
      disabled={isLoading}
      onMouseEnter={() => setIsHovering(true)}
      onMouseLeave={() => setIsHovering(false)}
      className={error ? 'hover:bg-red-50' : ''}
    >
      {getIcon()}
      <SidebarLabel>{getLabel()}</SidebarLabel>
      {getStatusIndicator()}
    </SidebarItem>
  )
}

Error Handling

Handle different error scenarios:

import { useArbolAssistant } from 'use-arbol-assistant'

function ErrorHandlingExample() {
  const { isLoading, isActiveSession, error, toggleSession } = useArbolAssistant('tenant-id')

  if (error) {
    return (
      <div className="rounded-lg border border-red-200 bg-red-50 p-4">
        <div className="flex items-start">
          <ExclamationTriangleIcon className="h-5 w-5 text-red-400" />
          <div className="ml-3">
            <h3 className="text-sm font-medium text-red-800">Connection Error</h3>
            <p className="mt-1 text-sm text-red-700">{error}</p>
            <button
              onClick={toggleSession}
              className="mt-2 rounded bg-red-100 px-3 py-1 text-sm text-red-800 hover:bg-red-200"
            >
              Retry Connection
            </button>
          </div>
        </div>
      </div>
    )
  }

  if (isLoading && !isActiveSession) {
    return <div>🔄 Connecting to AI assistant...</div>
  }

  if (isActiveSession) {
    return (
      <div>
        <div>🎤 Conversation active - speak now!</div>
        <button onClick={toggleSession}>End Conversation</button>
      </div>
    )
  }

  return <button onClick={toggleSession}>🚀 Start AI Conversation</button>
}

Loading States

Handle different loading states:

import { useArbolAssistant } from 'use-arbol-assistant'

function LoadingExample() {
  const { isLoading, isActiveSession, toggleSession } = useArbolAssistant('tenant-id')

  if (isLoading && !isActiveSession) {
    return <div>🔄 Connecting to AI assistant...</div>
  }

  if (isActiveSession) {
    return (
      <div>
        <div>🎤 Conversation active - speak now!</div>
        <button onClick={toggleSession}>End Conversation</button>
      </div>
    )
  }

  return <button onClick={toggleSession}>🚀 Start AI Conversation</button>
}

Requirements

• React 18+
• Modern browser with WebRTC support
• Microphone access permission
• Valid Arbol tenant ID

Browser Support

This library requires a modern browser with support for:

• WebRTC
• MediaDevices API
• Web Audio API
• ES2020 features

Built-in Features

The hook automatically handles:

• ✅ Audio streaming via WebRTC
• ✅ Automatic transcription of conversations
• ✅ Session cleanup on component unmount
• ✅ Connection retry logic
• ✅ OpenAI API integration

Configuration

The hook uses optimized defaults:

• Voice: alloy
• Model: gpt-4o-realtime-preview-2024-12-17
• API: https://dev-api.arbol.uno
• Debug mode: false

No configuration needed! 🎯

Development

To run the library in development mode:

# Install dependencies
bun install

# Build the library
bun run build

# Run type checking
bun run type-check

# Run linting
bun run lint

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

License

MIT © Arbol AI

Support

For support, please contact [email protected] or create an issue in our GitHub repository.