Appearance

Quick Start ​

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

Step 1: Install Sibilance Client ​

bash
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:

typescript
// 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 ​

typescript
// 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:

typescript
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:

tsx
// 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:

html
<!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:

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? ​

Copyright © 2025 sibilance.is