AmphiVox Widgets — React

 your app                       @amphivox/react           AmphiVox iframe           voice agent
 ────────                       ───────────────           ───────────────           ───────────
 form state, its rules,  ──►    page prop / reportPage ──► relays the page   ──►    asks, checks,
 Next and submit                controls (open, mute…)     and your controls        writes values
                         ◄──    onField, onAdvancePage,   ◄── relays the agent ◄──
                                onSessionEnd, …

npm install @amphivox/react

// The component: the page is a prop.
<VoiceWidget {...widgetOptions} page={{ page, values: pageValues }} onField={applyValue} />

// The hook: the page is your job.
const widget = useVoiceWidget({ ...widgetOptions, onField: applyValue })
const snapshot = JSON.stringify({ page, values: pageValues })
useEffect(() => { widget.reportPage(JSON.parse(snapshot)) }, [widget, snapshot])

1. Form renders      page={{ page: 0, values }}  (or reportPage)
2. Visitor taps mic  onSessionStart()
3. Visitor answers   onField('email', 'a@b.com', 'w_17')
                     → set it in state; the new `page` reports it
4. Your rule says no onField returns { ok: false, cause: 'validation', reason }
                     → the agent says why and asks again; after two
                       failed attempts it leaves the field to the visitor
5. Page 0 is done    the agent asks: "Anything to change before I move on?"
                     the visitor agrees → onAdvancePage()
                     → Next moved:  setPage(1); the new page reports itself
                     → Next failed: return false from onAdvancePage:
                       the agent goes back to an unanswered field,
                       or else ends the session (hands_off)
6. Visitor is silent the agent nudges, warns, then
                     onSessionEnd({ reason: 'timeout', detail: { timeout: 'idle' } })
7. Last page done    the agent reads the answers back, then
                     onSessionEnd({ reason: 'complete' }) → validate and submit

function VoiceButton({ page, values }: { page: number; values: Record<string, unknown> }) {
  const [live, setLive] = useState(false)
  const [botTalking, setBotTalking] = useState(false)
  const [muted, setMuted] = useState(false)
  const [lines, setLines] = useState<{ speaker: string; text: string }[]>([])

  const widget = useVoiceWidget({
    ...widgetOptions,
    hidden: true,
    onField: applyValue,
    onSessionStart: () => { setLive(true); setLines([]) },
    onSessionEnd: () => setLive(false),
    onSpeaking: (who, active) => { if (who === 'bot') setBotTalking(active) },
    onMuteChange: setMuted,
    onTranscript: (speaker, text, index) =>
      setLines(l => { const next = [...l]; next[index] = { speaker, text }; return next }),
  })
  const snapshot = JSON.stringify({ page, values })
  useEffect(() => { widget.reportPage(JSON.parse(snapshot)) }, [widget, snapshot])

  return (
    <>
      <button type="button" onClick={live ? widget.close : widget.open}>{live ? 'Stop' : 'Answer by voice'}</button>
      <button type="button" onClick={muted ? widget.unmute : widget.mute} disabled={!live}>{muted ? 'Unmute' : 'Mute'}</button>
      <select onChange={e => widget.setLanguage(e.target.value)} disabled={live}>
        <option value="en">English</option>
        <option value="hi">हिन्दी</option>
      </select>
      {botTalking && <span>Speaking…</span>}
      <ul>{lines.map((line, i) => <li key={i}>{line.speaker}: {line.text}</li>)}</ul>
    </>
  )
}

<VoiceWidget
  /* …the rest of your props… */
  page={{ page, values: pageValues }}
  onAdvancePage={async () => {
    const errors = await validatePage(page)
    if (errors.length > 0) return false   // the unchanged page is already reported
    setPage(p => p + 1)                   // the new page reports itself
  }}
/>

onField={(fieldId, value) => {
  if (isSkip(value)) return
  if (fieldId === 'email' && registeredEmails.has(value as string)) {
    return { ok: false, cause: 'validation', reason: 'That email already has an account.' }
  }
  setValues(v => ({ ...v, [fieldId]: value }))
}}

const widget = useVoiceWidget({
  ...widgetOptions,
  onField: (fieldId, value, writeId) => {
    if (isSkip(value)) return
    if (fieldId !== 'coupon') { setValues(v => ({ ...v, [fieldId]: value })); return }
    checkCoupon(value as string).then((valid) => {
      if (valid) setValues(v => ({ ...v, coupon: value }))
      else widget.reportWriteResult({
        fieldId, writeId: writeId!, ok: false, cause: 'validation', reason: 'That coupon has expired.',
      })
    })
  },
})

import { SKIP, isSkip } from '@amphivox/react'

const [skipped, setSkipped] = useState<string[]>([])
const initialValues = Object.fromEntries(skipped.map(id => [id, SKIP]))

<VoiceWidget
  /* …the rest of your props… */
  initialValues={initialValues}
  onField={(fieldId, value) => {
    if (isSkip(value)) {                  // not an answer: leave the field as it is
      setSkipped(s => (s.includes(fieldId) ? s : [...s, fieldId]))
      return
    }
    setSkipped(s => s.filter(id => id !== fieldId))
    setValues(v => ({ ...v, [fieldId]: value }))
  }}
/>

<input
  type="file"
  onChange={async (e) => {
    const file = e.target.files?.[0]
    if (!file || !acceptsFile(file)) return     // your own size and type check
    await uploadToYourServer(file)
    setValues(v => ({ ...v, cv: { uploaded: true } }))   // `null` until then
  }}
/>

<VoiceWidget
  /* …the rest of your props… */
  initialValues={{ full_name: user.name, email: user.email }}
/>

onSessionEnd={(ending) => {
  switch (ending.reason) {
    case 'complete':                        // every answer is in: validate and submit
      submitMyForm(values)
      break
    case 'hands_off':                       // the visitor must finish some fields
      highlightFields(ending.detail?.outstanding ?? [])   // their labels
      break
    case 'timeout':                         // 'idle' or 'max_duration'
    case 'manual':                          // the visitor stopped, or you called close()
      break                                 // nothing to do: their answers are in your state
    case 'error':                           // a live session failed; answers already written stay valid
      setNotice('Voice stopped working. You can finish the form by hand.')
      break
  }
}}

import type { WidgetError } from '@amphivox/react'

function handleVoiceError({ code, message }: WidgetError) {
  switch (code) {
    case 'origin_not_allowed':              // add this site to the key's allowed websites
    case 'invalid_widget_key':
    case 'widget_mode_mismatch':
      console.error('[voice setup]', code, message)
      break
    case 'widget_page_invalid':             // your page values and the schema disagree
      console.error('[voice page]', message)
      break
    case 'session_limit_exceeded':
    case 'session_busy':
      setNotice('Voice is busy right now. Try again in a minute.')
      break
    default:                                // the list can grow: always keep a default
      setNotice(message)
  }
}

import { useEffect, useState } from 'react'
import { useForm } from 'react-hook-form'
import { useVoiceWidget, isSkip } from '@amphivox/react'

function ApplicationForm() {
  const [page, setPage] = useState(0)
  const { register, setValue, watch, trigger, getFieldState, handleSubmit } = useForm()
  const pageIds = PAGE_FIELDS[page]   // this page's field ids

  const widget = useVoiceWidget({
    ...widgetOptions,
    onField: (fieldId, value, writeId) => {
      if (isSkip(value)) return
      setValue(fieldId, value, { shouldDirty: true })
      // Your library's rules decide; a failed rule is a validation refusal.
      trigger(fieldId).then((ok) => {
        if (!ok && writeId) widget.reportWriteResult({
          fieldId, writeId, ok: false, cause: 'validation',
          reason: getFieldState(fieldId).error?.message ?? 'That answer is not accepted.',
        })
      })
    },
    onAdvancePage: async () => {
      if (!(await trigger(pageIds))) return false   // blocked: the agent is told
      setPage(p => p + 1)
    },
    onSessionEnd: (ending) => {
      if (ending.reason === 'complete') handleSubmit(submitMyForm)()
    },
  })

  // The page report comes from the library's own values.
  const all = watch()
  const snapshot = JSON.stringify({ page, values: Object.fromEntries(pageIds.map(id => [id, all[id] ?? null])) })
  useEffect(() => { widget.reportPage(JSON.parse(snapshot)) }, [widget, snapshot])

  return <form>{/* …inputs registered with `register`… */}</form>
}

'use client'
import { VoiceWidget } from '@amphivox/react'

// Each key's own mode and key (and schema), like `widgetOptions`:
<VoiceWidget {...salesOptions} page={salesPage} position="bottom-right" />
<VoiceWidget {...supportOptions} page={supportPage} position="bottom-left" />

Content-Security-Policy: frame-src https://amphivox.com;