Skip to content

CW-Codewalnut/voice-ai-tool

BranchesTags

Repository files navigation

Voice AI Survey Tool

A free and open source self-hostable platform for creating and deploying conversational voice-based surveys powered by OpenAI's real-time models.

Key Features

  • 🎙️ Real-Time Voice Conversations: Engage users with a natural, conversational AI agent for a more interactive survey experience.
  • ⚙️ Configurable Survey: Easily configure survey questions, AI persona, voice models, and welcome/ending messages.
  • 🔒 Secure & Self-Hostable: Full control over your data with secure admin authentication and the ability to host on your own infrastructure.
  • 📊 Transcript Review: Access and review full transcripts of all completed survey sessions to analyze user feedback.
  • 🏗️ Modern Tech Stack: Built with a fully type-safe, modern stack including React, Hono, tRPC, and Drizzle ORM.

Table of Contents

Overview & Problem Statement

The Problem

Traditional web forms and text-based surveys often suffer from low engagement and completion rates. They can feel impersonal and fail to capture the nuance and detail present in natural human conversation, leading to superficial feedback.

The Solution

This Voice AI Survey Tool transforms the survey experience by replacing static forms with dynamic, voice-driven conversations. An AI agent, powered by OpenAI Realtime models, engages users in a natural dialogue, asking predefined questions and capturing their spoken responses in real-time. This approach makes feedback collection more engaging, accessible, and capable of gathering richer, more detailed insights.

Demo

Screenshots

Survey
initial UI state conversation in progress UI state response submitted UI state
Configuration Panel
system settings form

Product Features

  • Admin Dashboard
    • Secure Google OAuth login with email-based admin authorization.
    • Configurable admin access through environment variables - only specified email addresses can access admin features.
    • Intuitive interface to configure the AI's persona, including event information, welcome/ending messages, and special instructions.
    • Dynamic form to add, remove, and edit survey questions.
    • Selection of different model voices and speech speed.
  • Conversational Survey Interface
    • Simple "Start Survey" initiation.
    • Visual feedback for different states: initializing, listening, paused, completed.
    • Real-time, interactive conversation with the AI agent.
    • Ability to pause, resume, and end the survey at any time.
  • Transcript Management
    • A dedicated "Results" page in the admin dashboard.
    • Chronological list of all survey sessions.
    • Detailed view of each conversation, showing both user and AI messages.

Business Use Cases

  • Customer Feedback: Automate post-support call surveys to gather detailed, qualitative feedback on customer satisfaction.
  • Market Research: Conduct initial screening interviews or product concept testing with a consistent, unbiased AI interviewer.
  • Employee Engagement: Create an anonymous voice channel for employees to provide candid feedback on workplace culture.
  • Healthcare: Streamline patient intake by having an AI agent ask preliminary questions in a conversational manner.
  • Accessibility Testing: Gather verbal feedback from users with disabilities on website or app usability.

Tech Stack & Architecture

Core Technologies

Architecture Diagram

high level architecture diagram of the application

Sequence Diagram

mermaid sequence diagram of the application

Data Flow:

  1. Admin: An admin logs in via Google OAuth, configures the survey settings (prompts, questions, voice) in the React dashboard, and saves them.
  2. End-User: A user visits the survey page, starts the session, and the frontend obtains a ephemeral key from the backend and establishes a real-time connection with the OpenAI API.
  3. Conversation: The AI agent powered by OpenAI's GPT Realtime Model configured with the admin's settings, initiates a conversation.
  4. Transcript Logging: The entire conversation transcript is saved to the database for later review by the admin.

Folder Structure

The project is a monorepo managed by Turborepo and Bun Workspaces.

├── apps
│   ├── api        # Hono backend with tRPC endpoints & Better Auth
│   └── web        # React frontend application (Vite & React Router)
├── packages
│   ├── shared     # Shared code (Zod schemas, constants) between backend and frontend
│   └── tsconfig   # Shared TypeScript configurations
└── scripts
    └── setup.ts   # Automated setup script

Local Setup & Installation

Prerequisites

Step-by-Step Installation

  1. Clone the Repository

    git clone https://github.com/CW-Codewalnut/voice-ai-tool.git
cd voice-ai-tool

  2. Run the Setup Script This command will install all dependencies, copy the example .env files if missing (it will NOT overwrite existing ones), and run the initial database migration & seed the DB with a sample system settings.

    bun setup

  3. Configure Environment Variables The bun setup script creates .env files in apps/api and apps/web. You must fill them with your credentials.

    Backend (apps/api/.env)

    Variable Description Example
    APP_PORT Port for the backend server. 5000
    APP_URL Full public URL of the backend. http://localhost:5000
    ADMIN_EMAILS Semicolon-separated list of admin email addresses who can access admin features. admin@example.com;admin2@example.com
    CORS_ORIGINS Semicolon-separated list of allowed origins for CORS and auth trusted origins. http://localhost:3000;https://your-prod-domain.com
    DATABASE_URL Turso DB URL (libsql/http(s)) or local file URL for development. file:./.database/local.db
    DATABASE_AUTH_TOKEN Optional Turso auth token. Required for remote DB; omit for local file DB. your-turso-token
    GOOGLE_CLIENT_ID Your Google OAuth Client ID. your-google-client-id.apps.googleusercontent.com
    GOOGLE_CLIENT_SECRET Your Google OAuth Client Secret. your-google-client-secret
    AUTH_SECRET A long, random secret for signing auth tokens. Generate one with openssl rand -hex 32. a_very_long_and_random_secret_string
    OPENAI_API_KEY Your OpenAI API key. sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx

    Frontend (apps/web/.env)

    Variable Description Example
    VITE_APP_URL The full URL of your frontend application. http://localhost:3000
    VITE_API_URL The full URL of your backend API. http://localhost:5000

  4. Start the Development Servers This command uses Turborepo to start both the backend and frontend servers concurrently.

    bun dev
    • API will be running at http://localhost:5000
    • Web app will be running at http://localhost:3000

Database Commands

This project uses Drizzle ORM. You can manage the database with these commands:

  • bun db:studio: Opens the Drizzle Studio GUI to inspect your database.
  • bun db:generate: Generates SQL migration files based on schema changes.
  • bun db:migrate: Applies pending migrations to the database.

About

A voice-based survey tool using OpenAI's Realtime Models for interactive voice conversations and hands-free form completion.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages