Skip to main content

Setup

This guide covers everything you need to configure and initialize the Hidoba Research Voice Calls SDK.

Required Credentials​

Before using the SDK, you need to obtain these credentials from Hidoba Research:

Step-by-Step Setup​

1. Obtain Your Credentials

Contact Hidoba Research to receive:

  • Partner ID: Your unique identifier (e.g., "github:partner")
  • API Key: Your API key for authentication

2. Create AI Characters

Visit the Character Editor to create and customize your AI characters. You can define personality traits, conversation styles, and more. Your Partner ID is your login for the Character Editor.

3. Configure Your Application

Set up your constants and initialize the CallManager as shown below.

Security Note

Your API Key is tied to your account and usage limits. Keep it secure and don't share it publicly.

SDK Configuration Parameters​

Configure your SDK with these required parameters:

ParameterTypeDescriptionExample
BACKEND_URLStringBackend URL connected to your account (provided by Hidoba Research)"https://backend.funtimewithaisolutions.com"

SDK Initialization​

To initialize the SDK, you need to set up your configuration constants and create a CallManager instance:

// Set up your configuration constants
const BACKEND_URL = 'https://backend.funtimewithaisolutions.com';

// Define your callback functions
const callbacks = {
    onCallStart: () => { /* Handle call start */ },                    // Required
    onCallError: () => { /* Handle call errors */ },                   // Required
    onHangUp: () => { /* Handle hang up event */ },                    // Required
    onStatusUpdate: (status) => { /* Handle status updates */ },       // Required
    onCallStarting: () => { /* Handle call starting (after permissions) */ }, // Optional
    onConnected: () => { /* Handle successful connection */ },          // Optional
    onUserInfo: (info) => { /* Handle user info updates */ },          // Optional
    onRagInfo: (ragData) => { /* Handle RAG document info */ }         // Optional
};

// Create the CallManager instance
const callManager = new CallManager(callbacks);

Advanced Configuration Options​

The CallManager constructor accepts an optional config object with these settings:

OptionTypeDescriptionDefault
characterRoleStringDisplay name for the AI character in conversation historyCharacter name
personRoleStringDisplay name for the user in conversation history"You"
microphoneIdString or nullDevice ID from getAvailableDevices() or saved user preference. Use null for system defaultnull (system default)
speakerIdString or nullDevice ID from getAvailableDevices() or saved user preference. Use null for system defaultnull (system default)

Basic Configuration Example​

// Basic usage with display names only
const config = {
    characterRole: "Assistant",
    personRole: "User"
};

const callManager = new CallManager(callbacks, config);

Advanced Configuration Example​

// Advanced usage with device selection
const config = {
    characterRole: "Assistant",
    personRole: "User",
    microphoneId: "device123",  // Specific microphone device ID
    speakerId: "speaker456"     // Specific speaker device ID
};

const callManager = new CallManager(callbacks, config);

UI Implementation Requirements​

After initializing the SDK, you need to implement these essential UI components:

Call Control Buttons​

Your application needs UI elements to trigger call start and end actions (such as buttons or other interactive elements). These can be implemented as separate buttons or as a single button that changes its function based on call state.

Example implementation:

<button id="callButton">Call</button>
<button id="hangUpButton" disabled>Hang Up</button>

<script>
    // CallManager is already initialized as shown above
    const API_KEY = "YOUR_API_KEY";  // Your API key provided by Hidoba Research
    const PARTNER = "github:partner";   // Your partner identifier
    const CHARACTER = "character";     // Your character name
    
    document.getElementById('callButton').addEventListener('click', () => {
        callManager.handleCall2(PARTNER, CHARACTER, API_KEY);
    });
    
    document.getElementById('hangUpButton').addEventListener('click', () => {
        callManager.hangUp();
    });
</script>

Status Display​

Your application should include an element to display call status and user information:

<div>Status: <span id="statusText">Not connected</span></div>
<div>User Info: <span id="userInfoText"></span></div>

<script>
    // In your callbacks:
    const callbacks = {
        onCallStart: () => { /* Handle call start */ },
        onCallError: () => { /* Handle call errors */ },
        onHangUp: () => { /* Handle hang up event */ },
        onStatusUpdate: (status) => { // Required
            document.getElementById('statusText').textContent = status;
        },
        onUserInfo: (info) => { // Optional
            document.getElementById('userInfoText').textContent = info;
        }
        // ... other callbacks
    };
</script>

These UI elements are essential for proper functionality and user experience.

Next Steps​