Biz1 Onboarding AI Agent — Full Reference

Last updated: 2026-05-31

Setup assistant for **new org configuration**: guided chat + **free-text bulk** commands (fields, folders, tags, modules, email).

1. Where it lives

| Piece | Location |

|-------|----------|

| Logic | `include_file/biz1_agent_onboarding.php` |

| API controller | `application/controllers/Onboarding.php` |

| Modal UI | `application/views/include/onboarding_agent_modal.php` |

| Footer include | `application/views/include/footer.php` |

| Settings reopen | `application/views/new-design/setting.php` → **Setup assistant (AI)** |

| Config | `config.php` include + routes in `application/config/routes.php` |

| SQL | `sql/onboarding_agent_columns.sql` |

2. Who can use it

| Check | Function |

|-------|----------|

| Access | `biz1_onboarding_can_access()` → same as `biz1_agent_can_manage_settings()` |

| Allowed | **Org owner** OR **member_admin** (manager) |

| Auto-open | **Main account only** (`biz1_onboarding_is_main_account`) AND `onboarding_completed = 0` |

| Reopen anytime | Settings menu link (even after complete) |

Security

- All writes use `biz1_onboarding_session_org_id()` and `biz1_onboarding_session_user_id()` from session only - `biz1_onboarding_validate_context()` before every API call - Org reloaded from DB via session id — never from POST/AI JSON

3. API routes

| Method | Route | Action |

|--------|-------|--------|

| GET | `dashboard/onboarding/status` | Access, labels, auto_open, OAuth state |

| POST | `dashboard/onboarding/message` | Chat turn |

| POST | `dashboard/onboarding/apply` | Confirm pending bulk preview |

| POST | `dashboard/onboarding/complete` | Mark onboarding done |

| POST | `dashboard/onboarding/check_email` | Verify SMTP/Gmail/365 connected |

4. Database (`settings_of_user`)

Per **org owner** `user_id`:

| Column | Purpose |

|--------|---------|

| `onboarding_completed` | 1 = user clicked "I'm done" (stops auto-open) |

| `onboarding_step` | Wizard progress (optional) |

| `onboarding_business_type` | e.g. clinic, retail |

| `onboarding_business_description` | Free text |

| `onboarding_draft` | JSON draft (optional) |

| `onboarding_email_provider` | gmail / 365 / smtp |

| `onboarding_email_connected` | 1 after verified connection |

-- See sql/onboarding_agent_columns.sql for full ALTER

5. Interaction modes

5.1 Guided (chat)

User describes business in natural language → AI suggests modules, folders, next steps using static catalog `biz1_onboarding_business_catalog()`:

| Key | Suggested modules | Example folders |

|-----|-------------------|-----------------|

| `clinic` | appointment, whatsapp, payment | New leads, Active patients, Archive |

| `retail` | order, whatsapp, payment | Leads, Customers, VIP |

| `services` | Work_Flow, whatsapp | Leads, Projects, Done |

| `general` | whatsapp | Leads, Customers |

5.2 Free-text bulk (advanced)

Deterministic parser `biz1_onboarding_parse_bulk_block()` — no AI required for structure:

create fields
Budget, תקציב, number
Priority, עדיפות, select, High, Medium, Low

create folders
New leads
Active clients, לקוחות פעילים

create tags
VIP
Hot lead

create statuses
In progress
Waiting

enable modules appointment whatsapp payment

connect email gmail

**Pipeline:** parse → validate → clarify only invalid rows → preview → user **Apply**

Session pending: `$_SESSION['biz1_onboarding_pending']`

6. Field line format

english_name, hebrew_name, type[, option1, option2, ...]

Allowed types: `text`, `tel`, `email`, `number`, `radio`, `radio_custom`, `checkbox`, `select`, `date`, `textarea`, `link`, `title`

- `select` requires options (comma on same line or follow-up clarify) - Stored in `user_detail.extra_fields` JSON (same as Settings → Fields)

7. Apply executors

| Bulk type | Function | Target |

|-----------|----------|--------|

| Fields | `biz1_onboarding_apply_field()` | `user_detail.extra_fields` |

| Folders | `biz1_onboarding_apply_folder()` | `insert_folders()` |

| Tags | `biz1_onboarding_apply_tag()` | `tags` table |

| Statuses | `biz1_onboarding_apply_status()` | `custom_customer_status` JSON |

| Modules | `biz1_onboarding_apply_modules()` | `user_detail.module` JSON |

8. Email connect flow

1. User: "connect email" or picks provider chip (Gmail / 365 / SMTP) 2. Agent shows instructions (`biz1_onboarding_email_instructions()`) 3. UI buttons: - **Connect Gmail** → `gmailApi/othenticate.php` (OAuth, same as Settings) - **Connect Microsoft 365** → OAuth URL with session-derived `oauth_state` - **SMTP** → directs user to Settings → Email form 4. **Check connection** → reads `smtp_settings` for session org id

9. Languages (EN / HE / AR)

| Item | Implementation |

|------|----------------|

| UI labels | `biz1_onboarding_ui_label()` — title, buttons, placeholder |

| System errors | `biz1_onboarding_msg()` |

| AI replies | Prompt: reply in user language |

| RTL | Modal `dir="rtl"` when `lang` is `he` or `ar` |

| Bilingual data | Field lines: `name_en` + `name_he`; folder names support `en, he` on one line |

Settings menu label: - EN: Setup assistant (AI) - HE: עוזר הגדרה (AI) - AR: مساعد الإعداد (ذكاء اصطناعي)

10. UI behavior

| Action | Effect |

|--------|--------|

| Auto-open | ~1.2s after page load if `auto_open` from status |

| Settings link | `window.biz1OnboardingOpen()` / class `biz1-onboarding-open-settings` |

| Send | POST message → bubble + clarify/preview/email_setup |

| Apply | POST apply → runs pending bulk |

| I'm done | Sets `onboarding_completed=1`, closes modal |

| Clear chat | Resets history + pending UI |

11. Deployment notes

Deployed to dev: 2026-05-31 Backup pattern: `backup/onboarding-deploy-*/*.bck` on server

Files changed on deploy: - `config.php`, `routes.php`, `footer.php`, `setting.php` (with `.bck`) - New: `biz1_agent_onboarding.php`, `Onboarding.php`, `onboarding_agent_modal.php`

12. Related docs

- AI_AND_AUTOMATION_INDEX.md - BIZ1_SIDEBAR_AGENT.md — different agent (sidebar CRM, not onboarding) - SETTINGS_MAP.md — manual settings reference