Ear3 SDK

Two packages that together give you a signed, end-to-end voice interview flow: one for the browser (branded widget by default, headless SDK on a subpath) and one for your server.

npm install @ear3/voice-interviewer @ear3/server  # branded widget or headless SDK + server

// app/interview/page.tsx — branded turnkey widget, zero UI work
import { Ear3VoiceInterview } from '@ear3/voice-interviewer'
 
<Ear3VoiceInterview
  interviewId={process.env.NEXT_PUBLIC_EAR3_INTERVIEW_ID!}
  publishableKey={process.env.NEXT_PUBLIC_EAR3_VOICE_INTERVIEWER_KEY!}
  onComplete={(e) => router.push('/done')}
/>

Want a fully custom look instead? Same package, /headless subpath — import { Ear3Interview } from '@ear3/voice-interviewer/headless'.

Both modes call the same backend, mint identical sessions, fire the same webhooks. See Concepts for the mental model.

// app/api/webhooks/ear3/route.ts
import { Ear3 } from '@ear3/server'
 
const ear3 = new Ear3(process.env.EAR3_CONFIG_CLI_KEY!)
 
export async function POST(req: Request) {
  const rawBody = await req.text()
  const event = ear3.webhooks.constructEvent(
    rawBody,
    req.headers.get('ear3-signature')!,
    process.env.EAR3_WEBHOOK_SECRET!,
  )
  // event.type === 'interview.completed' → your business logic
}

What lives where

Package	Runs in	Responsibilities
`@ear3/voice-interviewer`	Browser	Root: `<Ear3VoiceInterview>` (branded widget). `/headless`: `<Ear3Interview>` (native RTVI), `VoiceClient`, hooks + plugins
`@ear3/server`	Your server	Verify webhooks, retrieve session state, admin ops

Available packages

Package root: <Ear3VoiceInterview> — the branded turnkey widget, zero UI work. /headless subpath: <Ear3Interview> native RTVI, VoiceClient + hooks + plugins. Full UI control either way.

@ear3/voice-interviewer

Server SDK. Retrieve session state, mint invite links, verify incoming webhook signatures. Node 18+, native fetch + crypto.

@ear3/server

Where to next

5-minute path from empty repo to live voice interview. Uses the branded widget — the shortest path to something working.

Quickstart

Same interview, no iframe. Branded widget or headless RTVI client in your React tree — full UI control, mic-permission in your origin.

Native component

Mental model: keys, sessions, webhooks, and the two integration modes.

Concepts

Copy-paste patterns: user correlation, chained interviews, custom UI.

Recipes

Ten most-common failure modes with diagnostics.

Troubleshooting

Quickstart