Quick Start

This guide will walk you through building your first voice survey with Sibilance.

Step 1: Install Sibilance Client

npm install @sibilance.is/client

Step 2: Get Your Survey Key

1. Visit sibilance.is
2. Sign up for an account
3. Create a new survey using the Survey Builder
4. Generate a Survey Key for your survey
5. Copy the key (starts with sibilance_)

Step 3: Create a Sibilance Client

Create a file to initialize your Sibilance client:

// survey.client.ts
import { SibilanceClient } from '@sibilance.is/client';

export const surveyClient = new SibilanceClient({
  surveyKey: 'sibilance_your_key_here', // Replace with your actual Survey Key
}, {
  onComplete: (yaml) => {
    console.log('Survey completed!', yaml);
    // Submit to your backend
    fetch('/api/survey-results', {
      method: 'POST',
      body: JSON.stringify({ results: yaml })
    });
  },
  onError: (error) => {
    console.error('Survey error:', error);
  }
});

Step 4: Start a Voice Session

// Start the voice session when user clicks a button
document.getElementById('start-survey')?.addEventListener('click', async () => {
  await surveyClient.connect();
});

// Stop the session
document.getElementById('stop-survey')?.addEventListener('click', async () => {
  await surveyClient.disconnect();
});

Step 5: Handle Survey Results

The survey will automatically collect data as users interact with it. When complete, the onComplete callback receives structured YAML data:

surveyClient.onComplete = (yaml) => {
  // yaml is an array of collected information
  console.log('Collected data:', yaml);
  
  // Example output:
  // [
  //   { field: 'name', value: 'John Doe', sourceStep: 'introduction' },
  //   { field: 'email', value: 'john@example.com', sourceStep: 'contact' },
  //   { field: 'project_type', value: 'residential', sourceStep: 'project_details' }
  // ]
  
  // Submit to your backend
  submitSurveyResults(yaml);
};

React Integration

If you're using React, here's a complete example:

// App.tsx
import { useSibilance, FloatingMicButton } from '@sibilance.is/client/react';

function App() {
  const { voiceState, surveyState, toggleSession } = useSibilance({
    surveyKey: process.env.NEXT_PUBLIC_SIBILANCE_SURVEY_KEY!,
  }, {
    onComplete: (yaml) => {
      console.log('Survey completed!', yaml);
      // Submit to your API
      fetch('/api/survey-results', {
        method: 'POST',
        body: JSON.stringify({ results: yaml })
      });
    }
  });

  return (
    <div>
      <h1>My Website</h1>
      <YourContent />
      
      {/* Floating microphone button */}
      <FloatingMicButton
        isConnected={voiceState.isConnected}
        onClick={toggleSession}
      />
      
      {/* Show survey progress */}
      {surveyState.isActive && (
        <div className="survey-status">
          <p>Survey in progress...</p>
          <p>Current step: {surveyState.currentStepId}</p>
        </div>
      )}
    </div>
  );
}

Complete Example

Here's a complete HTML example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Voice Survey Demo</title>
</head>
<body>
  <h1>Welcome to Our Survey</h1>
  <p>Click the microphone button to start the voice survey.</p>
  
  <button id="start-survey">Start Survey</button>
  <button id="stop-survey" style="display: none;">Stop Survey</button>
  <div id="status"></div>

  <script type="module">
    import { SibilanceClient } from '@sibilance.is/client';

    const client = new SibilanceClient({
      surveyKey: 'sibilance_your_key_here',
    }, {
      onComplete: (yaml) => {
        console.log('Survey completed!', yaml);
        document.getElementById('status').textContent = 'Survey completed!';
        
        // Submit to your backend
        fetch('/api/survey-results', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ results: yaml })
        });
      },
      onError: (error) => {
        console.error('Survey error:', error);
        document.getElementById('status').textContent = 'Error: ' + error.message;
      }
    });

    const startBtn = document.getElementById('start-survey');
    const stopBtn = document.getElementById('stop-survey');
    const status = document.getElementById('status');

    startBtn.addEventListener('click', async () => {
      try {
        await client.connect();
        startBtn.style.display = 'none';
        stopBtn.style.display = 'inline-block';
        status.textContent = 'Survey started! Speak to interact.';
      } catch (error) {
        status.textContent = 'Failed to start: ' + error.message;
      }
    });

    stopBtn.addEventListener('click', async () => {
      await client.disconnect();
      startBtn.style.display = 'inline-block';
      stopBtn.style.display = 'none';
      status.textContent = 'Survey stopped.';
    });
  </script>
</body>
</html>

What's Next?

Now that you have a basic voice survey integrated, explore these topics:

• Sibilance Client - Learn about all client methods
• React Integration - React-specific patterns and hooks
• Survey State - Track survey progress
• Recipes - Common use cases and patterns

Common Issues

Microphone Not Working

Ensure you're running on HTTPS. Browsers block microphone access on HTTP (except localhost).

Survey Not Loading

1. Check that your Survey Key is correct (starts with sibilance_)
2. Verify the survey is active in the Sibilance platform
3. Check domain restrictions allow your current domain
4. Check browser console for detailed error messages

Survey Not Completing

1. Ensure all required steps are completed
2. Check that the survey flow is properly configured
3. Verify the survey has a valid end step
4. Check browser console for errors

Need Help?

• 📧 Email: support@sibilance.is
• 🌐 Website: sibilance.is
• 📚 API Reference: /api