# NiceDial Web Connect — Product documentation

Website voice AI widget: visitors verify (form + OTP), then talk to a tenant-specific assistant in Hindi/English. Operators manage tenants and monitor calls from the admin dashboard.

## Client-facing preview

Share this public URL with prospects (no admin login):

- Integration guide + live widget: `/public/client-guide.php?tenant=nicedial-web`
- Short alias: `/public/preview.php`

Includes install steps, copy-paste embed snippet, visitor flow, and go-live checklist.

## Architecture

```
Visitor browser
  → visitor form + OTP (email SMTP + WChat WhatsApp)
  → ephemeral Realtime session (api/session.php)
  → WebRTC to OpenAI Realtime
  → on hang-up: transcript text (+ optional audio) stored
  → optional email of chat to tenant admin_email
```

Long-lived OpenAI keys never reach the browser. Sessions mint short-lived `ek_…` secrets server-side.

## Multi-tenant model

Each tenant is `tenants/{key}.json`.

### Form & verification

| Setting | Purpose |
|---------|---------|
| `require_visitor_gate` | Show form before call |
| `require_email_otp` | Send email OTP |
| `require_phone_otp` | Require WhatsApp + WChat OTP |
| `form.*.enabled/required/label` | Which fields appear |

At least one OTP channel must be enabled.

### SMTP (per tenant)

`smtp` block on the tenant. **Empty `host` inherits** (same chain as NiceGuard):

1. Tenant SMTP (if host set)
2. `nice-web-connect` global config
3. `ssl-monitoring/config.php`
4. **`nicedialtech/config.php`** (default for NiceDial)
5. Env `NWC_SMTP_*`

For `nicedial-web`, leave SMTP empty so it uses existing nicedialtech Gmail SMTP.

### WChat (per tenant)

`whatsapp.wchat_api_key` on the tenant. Empty → global `includes/config.php` / `NWC_WCHAT_API_KEY`.

Template: `nicedial_login_otp` via `POST {base}/api/v1/messages/template` (ssl-monitoring compatible).

### Admin email & transcripts

| Setting | Default | Effect |
|---------|---------|--------|
| `log_transcripts` | true | Store conversation **text** |
| `email_transcript_to_admin` | true | Email full chat to `admin_email` |
| `admin_email` | — | Inbox for transcript shares |
| `record_audio` | false | Browser records mic; uploads to `storage/recordings/{tenant}/` |
| `whatsapp_followup_enabled` | true when WChat ready | Realtime tool sends product/demo summary via WChat |

### Voice → WhatsApp continuation

During a call the visitor can say “send these details to my WhatsApp.” The model calls `send_whatsapp_followup`; the browser posts to `/api/whatsapp-followup.php`.

**Important:** Meta’s 24-hour customer-care window opens only when the **visitor messages you**. An OTP template does **not** open free-text. Default `followup_mode=auto` tries free text, then falls back to an approved Meta template (`whatsapp.followup_template`, default `nicedial_voice_details` with `{{1}}` name, `{{2}}` summary, `{{3}}` link).

Uses the verified visitor WhatsApp by default. Logs under `storage/whatsapp_followups/`.

Consultative sales style (ask inbound vs outbound, then agents, then recommend) is prompt + knowledge — not a hard IVR flow.

**Yes — conversation text is stored** when `log_transcripts` is on:

- Per call JSON: `storage/calls/{tenant}/{session_id}.json`
- Daily append log: `storage/transcripts/transcripts-{tenant}-{date}.jsonl`

**Audio recording** is optional and off by default. Enable `record_audio` and update `brand.consent`. Client uses `MediaRecorder` on the mic stream and POSTs to `/api/recording.php`.

## Admin dashboard

URL: `/admin/`

Auth: `admin_token` in `includes/config.php` or `NWC_ADMIN_TOKEN`.

Screens:

- **Overview** — tenants, SMTP/WChat readiness, quick links
- **Calls** — list + full transcript viewer
- **Leads** — verified visitors
- **Tenants** — edit form, OTP, SMTP, WChat, recording, admin email

## Embed

```html
<script src="https://YOUR_HOST/nice-web-connect/public/widget.js"
  data-tenant="your-tenant-key"
  data-api-base="https://YOUR_HOST/nice-web-connect"
  data-position="right"
  data-label="Talk"
  async></script>
```

Also: `/public/integrate.php` (needs admin token to save).

## API surface

| Endpoint | Role |
|----------|------|
| `GET/POST api/tenant.php` | Public tenant brand + form config |
| `POST api/visitor/start.php` | Lead + send OTP |
| `POST api/visitor/verify.php` | Verify OTP → `visitor_token` |
| `POST api/session.php` | Mint Realtime client secret |
| `POST api/transcript.php` | Store text + email admin |
| `POST api/recording.php` | Upload audio (if enabled) |
| `POST api/whatsapp-followup.php` | Send voice-call summary to WhatsApp (WChat) |
| `GET api/health.php` | Readiness |

## Storage layout

```
storage/
  visitors/{tenant}/     pending + verified OTP sessions
  leads/                 daily JSONL lead logs
  calls/{tenant}/        call records (text + metadata)
  transcripts/           daily transcript JSONL
  recordings/{tenant}/   optional audio files
  sessions/              concurrent session markers
  rate_limit/            rate limit files
```

Protect `storage/` from direct web access (`.htaccess` included).

## Security & compliance

- Prefer HTTPS for microphone / WebRTC
- Do not log secrets in tenant JSON committed to git
- Disclose transcription/recording in `brand.consent`
- Rate limits per IP for visitor OTP and sessions
- CORS via `allowed_origins`

## Operations checklist

1. Set OpenAI API key
2. Set admin token; open `/admin/`
3. Configure tenant `admin_email`
4. Confirm SMTP source on health/admin (nicedialtech for NiceDial)
5. Set WChat API key (global or tenant)
6. Embed widget on website origins listed in `allowed_origins`
7. Optionally enable `record_audio` with consent text

## Related products

- **ssl-monitoring (NiceGuard)** — SMTP + WChat OTP reference
- **nicedialtech** — default SMTP credentials for NiceDial properties