Talkform
google-gemini-3.8-flashrun 9 Sep 2026507,507 tokens
Instructions
Instructions — the case's current instructions
build a typeform competitor where the backend is identical to typeform with structured questions and answers, but the frontend is purely an AI voice interview, with the AI interviewer aware of what structured data it needs to fill in for the user, but asking in a more natural conversational way. get it running including auth just ask me for the API keys for the services you need.
build a typeform competitor where the backend is identical to typeform with structured questions and answers, but the frontend is purely an AI voice interview, with the AI interviewer aware of what structured data it needs to fill in for the user, but asking in a more natural conversational way. get it running including auth just ask me for the API keys for the services you need.
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:
-
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_KEYand click Save Keys. - The system immediately switches to GPT-4o and neural voice synthesis.
- Open the web interface at
-
Environment File (
.env):- Create or edit
.envin the project root:OPENAI_API_KEY=mock-openai-key-not-a-secret ELEVENLABS_API_KEY=xi-your-elevenlabs-key-here
- Create or edit
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_KEYis 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
# Install backend dependencies
npm install
# Build the frontend production bundle
npm run build
Run the Server
npm start
The server will start at http://localhost:3000 (or the port defined by PORT).
Run Tests
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:
- 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.
- 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.
- 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.
- 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.
- Completion & Thank You Screen:
- Displays the Typeform
thankyou_screensmessage. - Provides an answer recap and a Copy Typeform JSON button for inspection.
- Displays the Typeform
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 optionalinterviewer_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,itemsarray.- Each item contains
landing_id,token,response_id,landed_at,submitted_at, andanswersarray 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
transcriptandmetadata(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_...: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
curl -H "Authorization: Bearer tfp_live_demo_987654321fedcba0987654321" \
http://localhost:3000/forms/form_onboarding_01
Fetch Responses in Typeform Format
curl -H "Authorization: Bearer tfp_live_demo_987654321fedcba0987654321" \
http://localhost:3000/forms/form_onboarding_01/responses
Example Response Output:
{
"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-innode: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 andBearer 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:
- 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
bindfails withEPERM, 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 port3000. - 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_KEYseamlessly activates GPT-4o, Whisper STT, and OpenAI Neural TTS. - Storage: Node.js built-in
node:sqlitewas chosen for persistent storage to eliminate external native compilation issues across Node versions while providing full relational integrity, speed, and persistence indata/talkform.db.



