Quickstart

Get a real Ear3 voice interview embedded in a Next.js app in 5 minutes.

1. Clone the template

npx degit ear3-templates/nextjs-onboarding-starter my-app
cd my-app
npm install

2. Get your Ear3 credentials

Sign in at app.ear3.ai and:

a. Create an interview and deploy it

Interviews and deployments are two separate things in the dashboard. The interview is the template (questions, branching, voice settings). A deployment is a specific live instance of that template, scoped to a channel — Web, Prolific, etc.

• Interviews → New — give it a name and add 3-5 questions
• Open the interview and click Deploy — the Deployment Wizard walks you through picking a channel (start with Web) and any channel-specific options
• Finish the wizard — you’ll land on a page showing the Deployment ID (looks like cm…). Copy it.

That deployment id is what the SDK calls interviewId — pass it to <Ear3Interview interviewId="cm…" /> or ear3.sessions.create({ interviewId: 'cm…' }). The name is legacy; each interviewId really addresses a specific deployment.

Stuck on where a value lives, or getting a 404/401? The full walkthrough with formats and error decoding is on Get your keys.

b. Mint API keys

• Settings → API Keys → Create key
• Create three keys:
  • Publishable (pk_test_…) — safe to expose in the browser
  • Secret (sk_test_…) — server-only
  • Webhook signing (whsec_…) — server-only
• Copy each one immediately — secret + webhook are shown only once

c. Register a webhook endpoint

• Settings → Webhooks → Add endpoint
• URL: https://<your-domain>/api/webhooks/ear3 (see Deployment for tunneling options in dev)
• Subscribe to interview.completed

3. Configure the template

cp .env.example .env.local

Edit .env.local:

NEXT_PUBLIC_EAR3_VOICE_INTERVIEWER_KEY=pk_test_…
EAR3_CONFIG_CLI_KEY=sk_test_…
EAR3_WEBHOOK_SECRET=whsec_…
NEXT_PUBLIC_EAR3_INTERVIEW_ID=cm_…_your_deployment_id

4. Run it

npm run dev
# open http://localhost:3000

Flow:

1. / — landing page with “Start the interview” CTA
2. /interview — <Ear3VoiceInterview> mounts, fetches a session, and runs the voice conversation in your React tree
3. The participant grants mic access + answers the questions
4. /done?session=… — thank-you page with the session id
5. Your server receives interview.completed at /api/webhooks/ear3

What just happened

• Your browser POSTed to Ear3 with the publishable key + interview id
• Ear3 minted a one-time session and connected you to a Pipecat Cloud worker
• The component ran the RTVI voice flow directly in your React tree
• When the respondent finished, onComplete fired with the session id
• Your handler redirected; meanwhile Ear3 POSTed a signed event to your webhook

See Concepts for the full mental model.

Run the demo without setting up an interview

Don’t have an interview ready yet? Use a session URL we created for testing:

// app/interview/page.tsx
<Ear3VoiceInterview
  interviewId="dpl_demo_public"          // ← will be a public demo id (TBD)
  publishableKey="pk_demo_anyone_can_use" // ← TBD
  onComplete={(e) => router.push(`/done?session=${e.sessionId}`)}
/>

⚠️ Once you ship to production, replace these with your own keys.