Nora AI for Magento 2 — User Guide

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.

• Nora AI for Magento 2 — $199/month

• Magento 2 extension index
• Toweringmedia AI Core (required dependency)
• Magento 2 docs home

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

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

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

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

Stores → Configuration → Towering Media → Nora AI

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:

.tm-chatbot {
    --tm-chatbot-primary: #0ea5e9;
    --tm-chatbot-primary-end: #0284c7;
}

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.

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.

Human workflow:

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

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

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

• 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.

• 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.

• 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

Widget does not appear on storefront

1. Confirm Enable Chatbot = Yes for the store view you're viewing (not just Default Config scope).
2. Confirm AI Core is installed and Enabled = Yes in AI Core Settings.
3. Flush full_page cache: bin/magento cache:clean full_page.

Nora replies with fallback copy instead of AI responses

1. Check AI Core → General → Dry Run is set to No and Enable Live API Calls is Yes.
2. Verify your OpenAI API key is saved and the daily call budget is not exhausted.
3. 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

1. Confirm Escalation & Handoff → Enable Human Escalation = Yes.
2. Check admin ACL — the logged-in admin user needs Manage Chat Escalations permission.

Human escalation email was not received

1. Check Support Email Override — empty uses Magento store support email, which may not be configured.
2. Review var/log/exception.log for mail transport errors.

Agent Hunter token not working

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