Biz1 Sidebar AI Agent — Full Reference

Last updated: 2026-05-31

Natural-language assistant in the **right sidebar** on most CRM pages. Routes user intent → specialist → clarify UI or immediate execution.

1. Where it lives

| Piece | Location |

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

| UI | `application/views/include/sidebar.php` — chat form `#send_message_biz1agent` |

| Entry API | `POST dashboard/aicomponent/send_message` → `Aicomponent::send_message()` |

| Orchestrator | `include_file/biz1_agent.php` → `biz1_agent_process_turn()` |

| Executor (legacy) | `application/helpers/general_helper.php` → `creeate_mission_customer_reminder_sendmessage_with_ai()` |

| JS | `new/js/project-general-js/sidebarrr_newwwwwww-jquery.js` |

| Loaded via | `config.php` includes all agent files |

2. Architecture

(Architecture diagram: user message → API → specialists → clarify or execute.)

Routing order (first match wins)

1. **Automation specialist** — `biz1_agent_automation.php` if message looks like automation 2. **Settings specialist** — `biz1_agent_settings.php` if message looks like settings (owner/manager only) 3. **General router** — picks intent from `biz1_agent_intent_list()` 4. **General specialist** — fills fields from catalog; may clarify 5. **Execute** — `general_helper` runs DB action by `answer['type']`

3. Session state

| Key | Purpose |

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

| `$_SESSION['biz1_agent_draft']` | Active intent + collected fields `{type, fields:{}}` |

| `$_SESSION['chat_history']` | Last ~16 turns (capped by `biz1_agent_cap_history`) |

Clarify selections merge via `biz1_agent_merge_selection_message()` — user picks dropdown → `Selected: key=value [source:catalog]`.

4. Intent catalog

Defined in `biz1_agent_intent_list()` (`biz1_agent.php`):

| Domain | Types |

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

| **CRM** | `add_mission`, `add_customer`, `add_reminder`, `send_message`, `search_customer`, `advanced_search_customer`, `greetings` |

| **Expenses** | `add_expenses`, `add_expenses_with_file` |

| **Lists** | `list_suppliers`, `list_categories`, `list_folders`, `list_tags`, `list_status` |

| **Rooms** | `room_booking`, `list_rooms`, `check_room_availability` |

| **Config** | `add_folder`, `update_folder`, `add_field`, `add_tabs_setting`, `add_custom_field_for_tabs_setting` |

| **Automations** | `add_automation_full`, `add_automation_event`, `add_automation_actions` |

| **Settings** | `explain_settings`, `update_settings` |

| **Campaign** | `add_campaign` |

| **Reports** | `customer_sales`, `order_created_count` |

Prompt cases: XML blocks in `get_full_prompt()` inside `general_helper.php` (`<case_add_customer>`, etc.).

5. Specialists (separate files)

5.1 Settings — `biz1_agent_settings.php`

- **Who:** `biz1_agent_can_manage_settings()` — org owner OR `member_admin` - **Security:** `biz1_agent_settings_validate_session_context()` — session org/user must match; AI payload stripped of ids - **Modes:** explain vs update - **Executes inline** — does NOT use `general_helper` for saves - **Updatable keys:** `biz1_agent_settings_updatable_keys()` — see SETTINGS_MAP.md - **Languages:** EN / HE / AR system messages + AI reply in user language

5.2 Automation — `biz1_agent_automation.php`

- **Types:** `add_automation_event`, `add_automation_full`, `add_automation_actions` - **EVENT** = `automation_event` row (trigger) - **ACTION** = `automation` rows (steps) - Catalog: folders, tags, sources, team members, templates - Executes via automation insert helpers in `general_helper`

5.3 Folder — `biz1_agent_folder.php`

- **`biz1_agent_execute_update_folder()`** — partial folder updates (columns, tabs, share, SMTP, tags) - Used from sidebar when type is `update_folder` / `update_folder_columns` - Enriches catalog: tabs, SMTP list, companies, dashboard columns

6. AI API

| Function | Role |

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

| `biz1_agent_call_ai()` | OpenRouter / model call |

| `biz1_agent_parse_ai_json()` | Extract JSON from model text |

| `biz1_agent_enrich_clarify()` | Attach catalog options to dropdowns |

| `biz1_agent_build_catalog()` | Team, folders, tags, templates, columns, intents |

Catalog XML filtered per intent via `biz1_agent_catalog_xml_tags_for_type()`.

7. Clarify UI

When `status: clarify` (or router/specialist equivalent):

{
  "status": "clarify",
  "message": "Which folder?",
  "suggestions": [
    {
      "key": "folder_id",
      "label": "Folder",
      "source": "folder",
      "options": [{"id": "12", "name": "Leads"}]
    }
  ]
}

Frontend renders dropdowns; user selection sent as next message.

8. Security model

| Rule | Implementation |

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

| Login required | `check_login()` in controllers |

| Settings writes | Owner or manager only; session org id for all DB writes |

| Org context | `$Org['id']` must equal `session organizations_user_id` for settings agent |

| AI payload | Never trust `user_id`, `org_id`, `owner_id` from JSON — stripped before write |

| Sidebar CRM actions | Run as logged-in user; org from session via existing helper patterns |

9. Languages (EN / HE / AR)

- User message language → AI instructed to reply in same language (`$lang_explain`) - Settings agent: `biz1_agent_settings_msg()` + bilingual field names (`name_en` / `name_he`) - Sidebar UI strings: `$lang[...]` from `lang_en.php` / `lang_he.php` / `lang_ar.php` - RTL: site `css_site_lang` / `dir` on layout (sidebar inherits)

10. File attachment

`Aicomponent::send_message()` accepts `image_uploade_msg_side_ai` → FTP upload → passed as `$logo_name` to agent (used e.g. expense-from-file, folder icon).

11. Example user flows

**Add customer** > "Add customer John Smith phone 050-1234567" → `add_customer` → clarify missing folder/tag if needed → insert `contactus`

**Change settings (manager)** > "Turn on appointment module" → settings specialist → `module_toggle` → `update_user_detail`

**Create automation** > "When new lead from Facebook add tag VIP and send WhatsApp" → automation specialist → `add_automation_full` → insert event + steps

**Configure folder** > "On folder Leads show columns phone, email, source" → `update_folder` → `biz1_agent_execute_update_folder()`

12. What sidebar agent does NOT do

- Does **not** replace automation-table / canvas AI chats (those draft UI before save) - Does **not** run onboarding (separate modal — BIZ1_ONBOARDING_AGENT.md) - Does **not** edit permissions matrix (see PERMISSIONS_MAP — manual settings UI)

13. Related docs

- AI_AND_AUTOMATION_INDEX.md - SETTINGS_MAP.md - include_file/AUTOMATION_AI_BUILDER.md - PERMISSIONS_MAP.md