====== Nora AI for Magento 2 — User Guide ======

===== Extension context =====

This is the user guide for **Nora AI** (''toweringmedia/module-nora-ai''): an AI-powered storefront chat assistant for Magento 2. Nora answers product and policy questions instantly, gives signed-in customers read-only order help, and hands off to your support team via desktop Live Chat or the Agent Hunter mobile PWA when a human is needed.

Nora AI requires **Toweringmedia AI Core** — AI provider credentials, model selection, and call budgets are configured in AI Core, not here.

===== Product page =====

  * [[https://toweringmedia.com/nora-ai-for-magento-2|Nora AI for Magento 2 — $199/month]]

===== Quick links =====

  * [[magento2:extensions:start|Magento 2 extension index]]
  * [[magento2:extensions:toweringmedia-module-ai-core|Toweringmedia AI Core]] (required dependency)
  * [[magento2:start|Magento 2 docs home]]

===== Overview =====

Nora AI adds a floating chat widget to your storefront. It is not a rules-based chatbot — it reads live Magento data (catalog, CMS, config, customer orders) and routes questions through Toweringmedia AI Core's agent runtime to generate accurate, context-aware replies.

  * Guests get store, product, and policy answers — no private data exposed
  * Signed-in customers get the above plus read-only help on **their own** orders
  * Human escalation queues a chat for your support team via Live Chat or Agent Hunter
  * Unanswered escalations capture shopper name and email automatically

===== Requirements =====

^ Requirement ^ Notes ^
| Magento 2.4.x | Same baseline as your Toweringmedia stack |
| ''toweringmedia/module-base'' | Shared Toweringmedia admin tab and conventions |
| ''toweringmedia/module-ai-core'' | **Required** — AI provider, model, dry-run/live gates, budgets |
| PHP 8.1+ | Per ''composer.json'' |

===== Installation =====

<code bash>
composer require toweringmedia/module-nora-ai:^0.7 toweringmedia/module-ai-core:^2.1
bin/magento setup:upgrade
bin/magento cache:flush
</code>

Grant admin roles access under **System → Permissions → User Roles → Toweringmedia → Chatbot** (view logs, manage escalations, use Live Chat).

===== Go-live checklist =====

  - **AI Core** — provider enabled, model selected, live calls active for production (or accept dry-run/fallback during testing).
  - **Nora AI → General → Enable Chatbot** — set to **Yes** for each store view you want live.
  - Review **Widget Title**, **Launcher Label**, and **Welcome Message** — default values are neutral but you may want to brand them.
  - **Escalation & Handoff → Enable Human Escalation** — leave on if you want live handoff; ensure staff are trained on **Live Chat**.
  - **Security & Limits** — decide whether **Allow Guest Chat** should be on; adjust **Maximum Message Length** if needed.
  - Open the storefront, send a test message, confirm the session appears under **Conversations**.
  - Test handoff: say "speak to a person," claim in admin Live Chat, reply, confirm widget updates.
  - Optional: Test unanswered contact — request human, wait past timeout, confirm widget shows name/email form.
  - Optional: Set up **Agent Hunter** — generate API token, open PWA on phone, go on duty.

===== Admin path =====

**Stores → Configuration → Towering Media → Nora AI**

===== Configuration reference =====

==== General ====

^ Setting ^ Purpose ^
| Enable Chatbot | Master switch for widget and message endpoints on this store view |
| Widget Title | Panel header (shown in chat dialog) |
| Launcher Button Label | Text on the floating launcher button |
| Welcome Message | First message shown when there is no saved transcript yet |
| Help Notice | Optional hint below the message area (e.g., guest vs signed-in capabilities) |
| Empty Input Hint | Shown when a shopper tries to send a blank message |
| Unavailable Message | Shown when the chat endpoint is disabled or returns an error |
| Service Error Message | Shown when the browser cannot reach the chat service |
| Empty Message Reply | Server-side reply for blank input |
| Fallback Reply | Server-side reply when AI or tools cannot answer |
| Remember Chat in Browser | Restores transcript from browser storage on the same device (server history remains) |

==== Widget Appearance ====

Set primary color, header subtitle, launcher style, and unread badge behavior. Values are stored in Magento configuration — upgrading the module does not reset your branding.

Developers can override appearance with CSS variables in theme:

<code css>
.tm-chatbot {
    --tm-chatbot-primary: #0ea5e9;
    --tm-chatbot-primary-end: #0284c7;
}
</code>

Available tokens: ''--tm-chatbot-primary'', ''--tm-chatbot-primary-end'', ''--tm-chatbot-primary-foreground'', ''--tm-chatbot-bot-avatar-bg'', ''--tm-chatbot-messages-bg'', ''--tm-chatbot-card'', ''--tm-chatbot-muted-foreground'', ''--tm-chatbot-border'', ''--tm-chatbot-input-bg'', ''--tm-chatbot-radius'', ''--tm-chatbot-launcher-size''.

==== Voice (mic & read-back) ====

Requires Whisper STT and OpenAI TTS enabled in AI Core. When enabled, shoppers can click the mic button to speak their message and optionally receive spoken replies. Both features can be toggled independently.

==== Escalation & Handoff ====

^ Setting ^ Purpose ^
| Enable Human Escalation | When off, no escalation queue and no human handoff tool routing |
| Support Email Override | Override for the email sent when an escalation goes unanswered; falls back to Magento store email |
| Additional Handoff Trigger Phrases | One phrase per line — always forces handoff when matched |
| Handoff Unavailable Message | Shown if shopper asks for a human but escalation is disabled |
| Unanswered contact timeout (seconds) | If no agent sends a human reply within this window (default **30**, range 10–300), the widget asks for name + email and sends a notification email to the store inbox |

**Human workflow:**

  - Shopper requests a human (phrase, intent, or AI handoff tool)
  - Escalation row is created (open); bot pauses for that session
  - Agent sees notification in admin, opens **Live Chat**, claims the chat
  - Agent replies from **Live Chat** or **Agent Hunter** on mobile
  - Agent marks resolved; transcript goes to **Conversations**; FAQ-style exchanges may generate **Knowledge Base** draft entries for approval

==== Security & Limits ====

^ Setting ^ Purpose ^
| Allow Guest Chat | When off, only signed-in customers can send messages |
| Maximum Message Length | Enforced in widget and server (100–8000 characters) |
| Message Too Long / Guest Disabled replies | Server responses for those edge cases |

==== Agent Hunter ====

Agent Hunter is a mobile PWA for support staff away from their desk.

^ Step ^ Action ^
| 1 | **Customer Experience → Agent Hunter → Generate API token** (copy immediately; shown once) |
| 2 | Open **Agent Hunter app** on phone at ''/tm_chatbot/agent/app'' and add to home screen |
| 3 | Paste the token, enable **On duty** |
| 4 | When escalation arrives, claim from queue, reply, mark resolved |

Web Push (VAPID) keys are required for background phone alerts. Generate via the same screen after agents install the PWA and enable notifications.

===== Admin workspace areas =====

^ Area ^ Menu ^^ Use ^
| **Live Chat** | Customer Experience → Live Chat || Operator inbox — claim open chats, reply, resolve |
| **Conversations** | Customer Experience → Conversations || Review all storefront transcripts with bot-only / human / escalated filters |
| **Knowledge Base** | Customer Experience → Knowledge Base || Approve AI-screened FAQ drafts generated from resolved human chats |
| **Agent Hunter** | Customer Experience → Agent Hunter || Generate mobile API tokens and VAPID keys |

===== Storefront behavior =====

  * **Widget** — appears on default storefront layout when enabled; launcher button is always visible.
  * **Guests** — store info, CMS/policy content, catalog search. No account or order data.
  * **Signed-in customers** — above plus owned-order reads (status, summary, tracking, cancellation eligibility).
  * **Transcript persistence** — session + visitor IDs stored locally for continuity; server history retained for admin review regardless of browser storage.

===== Endpoints =====

  * ''GET /tm_chatbot/message/dryrun'' — chat turns (route name is historical; uses LLM when AI Core allows live calls)
  * ''GET /tm_chatbot/message/sessionMessages'' — delivers human agent messages during takeover
  * ''GET /tm_chatbot/message/submitEscalationContact'' — shopper submits name/email when escalation is unanswered past timeout

Disable **Enable Chatbot** to hide the widget and return inactive behavior on all endpoints.

===== Technical specifications =====

  * **Magento Version:** 2.4.x (Open Source & Adobe Commerce)
  * **PHP Version:** 8.1, 8.2, 8.3, 8.4
  * **Composer package:** ''toweringmedia/module-nora-ai''
  * **Current version:** 0.7.0
  * **Magento module name:** ''Toweringmedia_NoraAi''
  * **Requires:** ''toweringmedia/module-base'' ^1.1.23, ''toweringmedia/module-ai-core'' ^2.1
  * **Admin path:** Stores → Configuration → Towering Media → Nora AI
  * **License:** Proprietary — monthly subscription; remote entitlement validation via AI Core

===== Troubleshooting =====

**Widget does not appear on storefront**
  - Confirm **Enable Chatbot = Yes** for the store view you're viewing (not just Default Config scope).
  - Confirm AI Core is installed and **Enabled = Yes** in AI Core Settings.
  - Flush full_page cache: ''bin/magento cache:clean full_page''.

**Nora replies with fallback copy instead of AI responses**
  - Check AI Core → General → Dry Run is set to **No** and Enable Live API Calls is **Yes**.
  - Verify your OpenAI API key is saved and the daily call budget is not exhausted.
  - Check AI Core Test Connection in admin to confirm the key is valid.

**Shopper asked for a human but no escalation appeared in Live Chat**
  - Confirm **Escalation & Handoff → Enable Human Escalation = Yes**.
  - Check admin ACL — the logged-in admin user needs **Manage Chat Escalations** permission.

**Human escalation email was not received**
  - Check **Support Email Override** — empty uses Magento store support email, which may not be configured.
  - Review ''var/log/exception.log'' for mail transport errors.

**Agent Hunter token not working**
  - Tokens are single-use display — if missed, generate a new one.
  - Ensure the agent has the **Manage Chat Escalations** ACL.
  - For push alerts, VAPID keys must be generated and the PWA must have notification permission granted on the device.