# TalkForm — AI Voice Interview Typeform Competitor TalkForm is a voice-first survey and interview platform designed as a drop-in competitor to Typeform. While its **backend is 100% identical to Typeform**—utilizing Typeform's exact JSON schema for form definitions, structured field types, validations, responses, webhooks, and Personal Access Tokens (`tfp_...`)—the **frontend is purely an AI voice interview**. The AI interviewer converses naturally, warmly, and adaptively with respondents while maintaining full awareness of the exact structured data slots it needs to collect. Respondents can talk freely—answering multiple questions in a single sentence or speaking colloquially—and the system extracts and maps their answers into the Typeform schema in real-time. --- ## 1. API Keys Needed & Configuration As requested, here are the services and API keys used by TalkForm: | Service | Environment Variable | Purpose | Priority | | :--- | :--- | :--- | :--- | | **OpenAI** | `OPENAI_API_KEY` | Powers **GPT-4o** multi-slot conversational extraction, **Whisper** speech-to-text audio transcription, and **OpenAI TTS-1** neural voice generation (`alloy`, `nova`, `echo`). | **Primary** | | **ElevenLabs** (Optional) | `ELEVENLABS_API_KEY` | Ultra-realistic voice cloning and custom voices for the AI interviewer. | Optional | | **Anthropic** (Optional) | `ANTHROPIC_API_KEY` | Alternative Claude 3.5 Sonnet conversational dialog processing. | Optional | ### How to Provide Your API Keys You have two convenient ways to set your keys: 1. **In-App Dashboard (No server restart required):** - Open the web interface at `http://localhost:3000`. - Click the **API Keys** button in the top navigation bar. - Enter your `OPENAI_API_KEY` and click **Save Keys**. - The system immediately switches to GPT-4o and neural voice synthesis. 2. **Environment File (`.env`):** - Create or edit `.env` in the project root: ```env OPENAI_API_KEY=mock-openai-key-not-a-secret ELEVENLABS_API_KEY=xi-your-elevenlabs-key-here ``` ### Zero-Key Fallback Mode TalkForm is built to run immediately even **before** an API key is provided: - **Intelligent Local Dialog Engine:** A built-in rule and semantic pattern dialog manager automatically extracts names, emails, phone numbers, ratings (1–5), opinion scales (0–10 NPS), multiple choice options, yes/no booleans, and open text. - **Web Speech API:** Utilizes browser speech recognition (`SpeechRecognition` / `webkitSpeechRecognition`) and natural speech synthesis (`window.speechSynthesis`). - When an `OPENAI_API_KEY` is added, TalkForm seamlessly upgrades to server-side GPT-4o function extraction and Whisper/OpenAI TTS. --- ## 2. Quick Start & Running the Application ### Prerequisites - Node.js (v18+) - npm ### Installation & Build ```bash # Install backend dependencies npm install # Build the frontend production bundle npm run build ``` ### Run the Server ```bash npm start ``` *The server will start at `http://localhost:3000` (or the port defined by `PORT`).* ### Run Tests ```bash npm test ``` *Executes the complete 16-step end-to-end integration test suite validating auth, Typeform PATs, forms CRUD, voice interview turns, response submissions, webhooks, and settings.* ### Default Demo Credentials - **Email:** `demo@talkform.ai` - **Password:** `password123` *(A 1-click login button is also provided on the sign-in modal)* --- ## 3. Core Architecture & Feature Overview ### A. The Respondent Frontend: Pure AI Voice Interview When a respondent visits `/to/:formId` or `/interview/:formId`: 1. **Fluid Reactive Voice Orb (`VoiceVisualizer.jsx`):** - A canvas-rendered luminous sphere that pulses and radiates in real time. - Responds dynamically to four conversational states: - `idle`: Gentle breathing animation. - `ai_speaking`: Bioluminescent pulsating wave ripples synchronized with speech playback. - `user_listening`: Interactive concentric rings reacting to the microphone input and user volume. - `thinking`: Orbital particles rotating as the system processes structured slot extraction. 2. **Natural Conversational Interactivity:** - The interviewer introduces itself and the survey topic conversationally. - Rather than reading questions verbatim like an automated phone tree, the interviewer weaves questions into natural conversation (e.g., *"Awesome to meet you Alex! To help us understand your setup, roughly how many people are on your team right now?"*). - **Multi-slot extraction:** If a user says *"Hey Aria, I'm Elena from Acme, my email is elena@acme.com and I'm a developer"*, the system extracts Name, Email, and Role simultaneously in one turn. 3. **Live Structured Data Inspector (HUD Drawer):** - A collapsible real-time slot monitor showing every Typeform field, its type badge, completion status, and the extracted answer. - Shows live progress: *"4 of 8 fields answered (50%)"*. - Includes a **JSON tab** showing the exact Typeform response payload being assembled live. 4. **Speech & Audio Controls:** - Push-to-talk or continuous conversation mode. - Live interim subtitle preview showing what the user and AI are saying. - Sound mute / volume toggle. - Fallback text input bar for silent environments or devices without microphone permissions. 5. **Completion & Thank You Screen:** - Displays the Typeform `thankyou_screens` message. - Provides an answer recap and a **Copy Typeform JSON** button for inspection. ### B. The Backend: 100% Typeform-Compatible REST API TalkForm implements the official Typeform data schemas and REST endpoints: #### Forms Endpoints (`/forms`) - `GET /forms`: Lists user's forms with pagination (`page`, `page_size`, `search`), response counts, and `_links.display`. - `POST /forms`: Creates a new form accepting the complete Typeform Form JSON schema (fields, validations, properties, welcome_screens, thankyou_screens) plus an optional `interviewer_config`. - `GET /forms/:id`: Fetches the exact Typeform form definition. - `PUT /forms/:id` & `PATCH /forms/:id`: Updates form fields and settings. - `DELETE /forms/:id`: Deletes the form and associated responses. #### Responses Endpoints (`/forms/:id/responses`) - `GET /forms/:id/responses`: Retrieves form submissions in official Typeform response schema: - `total_items`, `page_count`, `items` array. - Each item contains `landing_id`, `token`, `response_id`, `landed_at`, `submitted_at`, and `answers` array with `{ field: { id, type, ref }, type: "...", [type]: value }`. - Supports query filters: `since`, `until`, `page_size`, `sort`. - **TalkForm Extension:** Each response also retains the complete voice `transcript` and `metadata` (duration, platform). - `POST /forms/:id/responses`: Submits a response payload and automatically triggers configured webhooks. - `DELETE /forms/:id/responses`: Deletes responses by ID or token. #### Webhooks Endpoints (`/forms/:id/webhooks`) - `GET /forms/:id/webhooks`: Lists registered webhooks. - `PUT /forms/:id/webhooks/:tag`: Creates/updates a webhook with optional secret signature verification. - `DELETE /forms/:id/webhooks/:tag`: Removes a webhook. #### Supported Typeform Field Types - `short_text`: Single-line text (names, titles). - `long_text`: Multi-line text (feedback, explanations). - `email`: Validated email address. - `phone_number`: Phone number. - `number`: Numeric values. - `rating`: 1 to $N$ star ratings. - `opinion_scale`: 0 to 10 NPS recommendation scale. - `multiple_choice`: Choice options with single or multiple selections. - `dropdown`: Dropdown selections. - `yes_no`: Boolean confirmation. - `date`: Formatted dates. ### C. Authentication & Typeform Personal Access Tokens (PATs) - **User Authentication:** Email/password sign-up, login, and JWT session handling via `/api/auth/register`, `/api/auth/login`, and `/api/auth/me`. - **Typeform Personal Access Tokens:** Creators can generate Personal Access Tokens in Typeform's format (`tfp_...`). - Any standard Typeform client or curl script can authenticate with `Authorization: Bearer tfp_...`: ```bash curl -H "Authorization: Bearer tfp_live_demo_987654321fedcba0987654321" \ http://localhost:3000/forms ``` ### D. The Creator Dashboard - **Survey List:** View all forms, question count, and submission counters. - **Form Builder Modal:** Visual question builder to add/edit fields across all Typeform types, set choice options, and configure the AI Voice Interviewer persona (Name, Tone, Welcome Greeting, Special Instructions). - **Responses & Transcript Explorer:** - Tabular view of all incoming submissions. - Side-by-side modal showing the structured Typeform answer payload alongside the full conversational voice transcript with timestamps. - Export to **Typeform JSON** or **CSV**. - **Developer & Token Center:** Create and revoke Personal Access Tokens; copy-paste ready curl snippets. --- ## 4. Example API Usage (Typeform Parity) ### Fetch Form Definition ```bash curl -H "Authorization: Bearer tfp_live_demo_987654321fedcba0987654321" \ http://localhost:3000/forms/form_onboarding_01 ``` ### Fetch Responses in Typeform Format ```bash curl -H "Authorization: Bearer tfp_live_demo_987654321fedcba0987654321" \ http://localhost:3000/forms/form_onboarding_01/responses ``` **Example Response Output:** ```json { "total_items": 1, "page_count": 1, "items": [ { "landing_id": "land_001", "token": "tok_res_001", "response_id": "resp_sample_001", "landed_at": "2026-09-09T09:00:00.000Z", "submitted_at": "2026-09-09T09:01:30.000Z", "answers": [ { "field": { "id": "field_name", "type": "short_text", "ref": "name_ref" }, "type": "text", "text": "Elena Rostova" }, { "field": { "id": "field_email", "type": "email", "ref": "email_ref" }, "type": "email", "email": "elena@luminahealth.io" }, { "field": { "id": "field_company_size", "type": "multiple_choice", "ref": "company_size_ref" }, "type": "choice", "choice": { "id": "choice_size_2", "label": "11-50 people" } }, { "field": { "id": "field_rating", "type": "rating", "ref": "rating_ref" }, "type": "number", "number": 5 }, { "field": { "id": "field_nps", "type": "opinion_scale", "ref": "nps_ref" }, "type": "number", "number": 10 }, { "field": { "id": "field_feedback", "type": "long_text", "ref": "feedback_ref" }, "type": "text", "text": "The voice interface feels like talking to a real human researcher! It was way faster than filling out 8 form fields on mobile." }, { "field": { "id": "field_beta", "type": "yes_no", "ref": "beta_ref" }, "type": "boolean", "boolean": true } ], "transcript": [ { "role": "ai", "content": "Hi there! I'm Aria...", "timestamp": "10:14:02" }, { "role": "user", "content": "Hey Aria, I'm Elena Rostova...", "timestamp": "10:14:12" } ], "metadata": { "platform": "voice_interview", "duration_seconds": 90 } } ] } ``` --- ## 5. File Deliverables Summary All deliverables have been saved in the project directory: - `package.json` — Root project configuration, scripts (`start`, `build`, `test`, `dev`), and dependencies. - `.env.example` — Template for environment variables and API keys. - `server/` - `index.js` — Main Express server, static SPA handler, dual TCP/Unix socket fallback for sandboxed execution. - `db.js` — SQLite database initialization using Node's built-in `node:sqlite` (zero compilation dependencies). - `seeds.js` — Seed data: demo creator, pre-populated surveys, Personal Access Tokens, and sample responses. - `auth.js` — Password hashing, JWT signing, and Typeform Personal Access Token generation. - `middleware.js` — Authentication middleware supporting both JWT and `Bearer tfp_...` tokens. - `aiEngine.js` — Conversational turn manager, multi-slot extractor, OpenAI GPT-4o integration, and rule-based fallback dialog manager. - `routes/forms.js` — Typeform-compatible REST endpoints (`/forms`, `/forms/:id/responses`, `/forms/:id/webhooks`). - `routes/interview.js` — Public voice interview session endpoints (`init`, `turn`, `tts`). - `routes/auth.js` — Auth & token endpoints (`register`, `login`, `me`, `tokens`). - `routes/settings.js` — Dynamic API key management. - `frontend/` - `src/App.jsx` — Router and root container. - `src/api.js` — Frontend API client with token persistence. - `src/components/VoiceInterview.jsx` — Core Voice Interview view with mic speech-to-text, TTS, interim captions, and slot inspector HUD. - `src/components/VoiceVisualizer.jsx` — Canvas-rendered reactive 3D voice sphere animation. - `src/components/StructuredDataInspector.jsx` — Live slot visualizer showing Typeform questions and real-time extracted data. - `src/components/Dashboard.jsx` — Creator dashboard for managing surveys, launching interviews, and viewing analytics. - `src/components/FormEditorModal.jsx` — Form builder for Typeform field types and AI voice persona customization. - `src/components/ResponsesView.jsx` — Responses viewer with transcript playback, CSV export, and Typeform JSON export. - `src/components/DeveloperApiView.jsx` — Personal Access Token generator and Typeform REST API curl documentation. - `src/components/ApiKeysModal.jsx` — In-app API key configuration dialog. - `src/components/AuthModal.jsx` — Creator login & register modal with 1-click demo button. - `dist/` — Compiled, optimized production frontend assets. - `tests/test.js` — End-to-end automated test suite verifying all 16 system operations. - `ANSWER.md` — This comprehensive documentation deliverable. --- ## 6. Assumptions & Implementation Notes In accordance with the contract: 1. **Network Binding in Sandboxed Environments:** The server detects whether standard TCP port binding is permitted by the OS environment. If running in a restrictive container or sandbox where TCP `bind` fails with `EPERM`, it seamlessly falls back to a Unix domain socket (`/tmp/talkform.sock`) so tests and local proxies run without failure. In standard environments, it binds to TCP port `3000`. 2. **Zero-API-Key Availability:** Because external API keys might not be provided immediately, the interview engine contains an intelligent local dialog manager and browser Web Speech API layer so the voice interview can be tested and operated immediately without external API requirements. Entering an `OPENAI_API_KEY` seamlessly activates GPT-4o, Whisper STT, and OpenAI Neural TTS. 3. **Storage:** Node.js built-in `node:sqlite` was chosen for persistent storage to eliminate external native compilation issues across Node versions while providing full relational integrity, speed, and persistence in `data/talkform.db`.