10 talkform

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:

     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

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

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_...:

  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-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.