LocalBot AI – Documentation v1.1.2

Thank you for purchasing LocalBot AI. This guide explains how to install, configure, and use the plugin on your WordPress site.

1. Overview

LocalBot AI is a Gemini‑powered AI chatbot and lead capture plugin for local service businesses (plumbers, electricians, HVAC, roofers, cleaners, and more).

• Floating chat widget on the front end
• AI chat using your own Google Gemini API key
• Emergency keyword detection and after‑hours fallback
• Lead capture form with configurable fields
• Admin dashboard with leads, analytics, logs, and locations
• Email notifications and optional webhook integration

2. Requirements

• WordPress 6.0+
• PHP 8.0+
• A Google Gemini API key from Google AI Studio

3. Installation

1. Download the plugin ZIP from Envato.
2. In WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Upload the ZIP and click Install Now, then Activate.
4. You will see a new menu item: LocalBot AI in the left sidebar.

4. 5-Minute Setup (Do This First)

1. Activate the plugin from Plugins.
2. Add Gemini API key at LocalBot AI → Settings → API, then click Test.
3. Add business basics at Settings → General (business name, phone, service area, hours, timezone).
4. Open your website front end and send one test message in the chat widget.
5. Submit a test lead and confirm it appears in LocalBot AI → Leads.

5. Quick Start

5.1 Configure business details

1. Go to LocalBot AI → Settings → General.
2. Fill in:
   • Business name
   • Business phone and optional Emergency phone
   • Service area (e.g. “Dallas, TX”)
   • Hours open / close and Timezone
3. Check the “Current time in this timezone” line to verify that the plugin understands your hours correctly (it will tell you if the bot is currently within business hours or after hours).
4. Click Save settings.

5.2 Connect Gemini API

1. Go to LocalBot AI → Settings → API.
2. Paste your Gemini API key from Google AI Studio.
3. Select a model (for example gemini-2.0-flash).
4. Set Max output tokens (150–400 is usually enough for short lead‑capture replies).
5. Click Test. A small “Connected” label should appear if the key is valid.

5.3 Choose niche & prompt

1. Go to Settings → Template.
2. Select a Business niche (plumber, electrician, HVAC, etc.).
3. Optionally add a Custom prompt:
   • You can use placeholders: {business_name}, {service_area}, {emergency_phone}
   • Example:

You're a friendly AI assistant for {business_name} in {service_area}.
Always prioritize emergencies and make sure to collect the visitor's name, phone, service type, and zip code.

4. Optionally add FAQ / knowledge text. This is appended to the system prompt and used when relevant.

5.4 Configure widget & lead form

1. Go to Settings → Widget:
   • Choose Position (Bottom right / Bottom left).
   • Set Primary color, widget title, welcome message, and input placeholder.
   • Decide whether to Show on mobile, and whether to auto‑open the chat after delay.
2. Go to Settings → Lead Form:
   • Toggle which fields to collect: name, phone, email, zip code, service type.
   • Edit Service options (comma‑separated list).
   • Decide if Phone is required.
   • Optionally require a consent (GDPR) checkbox and set a Privacy Policy URL.
   • Customize the Thank you message shown after submission.

5.5 Notifications & integrations

• Settings → Notifications
  • Enable email notifications and set the notify email address.
  • Customize the email subject (supports {name}, {service}).
  • Optionally include the chat transcript in the email.
  • Enable a “Review” link after lead submit (e.g. Google review URL).
• Settings → Integrations
  • Set a Webhook URL to receive JSON lead payloads.
  • Set a Webhook secret (HMAC key). The plugin will sign payloads with X-LocalBot-Signature.

6. Demo Data

For preview purposes, you can import demo leads and analytics:

1. Go to LocalBot AI → Dashboard.
2. Click the Import demo data button.
3. If there are currently no leads in the database, the importer will:
   • Create a demo location.
   • Create one demo chat session and lead.
   • Insert one demo analytics row for today.

You can now explore the Dashboard, Leads, and Analytics screens using sample data.

7. Admin Screens

7.1 Dashboard

• Top summary cards:
  • Leads today
  • Emergency today (leads marked as emergency)
  • Won leads (status = won)
• Lead management table: snapshot of recent leads (name, phone, service, urgency, status).
• Setup progress block: shows 3 onboarding checks (API connected, widget configured, test lead captured).
• Readiness snapshot block: highlights service-area setup and UTM-tracking readiness for local campaigns.
• Operational insights block:
  • Shows token usage for today and the last 30 days.
  • Shows recent quota/rate-limit event timing when detected.
  • Links directly to Google AI Studio and Analytics.

7.2 Leads

• Filter leads by Status (new / contacted / won / lost) and Urgency (emergency / normal / unknown).
• Click View to open an individual lead:
  • See basic details (name, phone, session id, service type).
  • See traffic source metadata (source URL, referrer, and UTM values when available).
  • View the chat transcript.
  • Add internal notes and save them.
• Update lead Status inline from the list.
• Export all leads as CSV via the Export CSV button.

7.3 Locations

• Add locations with name, address, phone, hours, timezone, default flag and sort order.
• Mark a location as Default.
• Delete locations from the table (with confirmation).

7.4 Analytics

Shows one row per day with:

• Chat requests
• Leads created
• Gemini errors
• Quota / 429 errors
• Rate limit hits
• Estimated token usage

7.5 Logs

Lists recent log entries from:

• Gemini API errors
• Webhook delivery problems
• Rate limit events

7.6 Settings

Tabs:

Tab	Description
General	Business information, phone numbers, service area, hours, timezone.
API	Gemini API key, model, max tokens, temperature, per‑IP rate limit.
Template	Niche, optional custom prompt, FAQ / knowledge and emergency keywords.
Widget	Position, colors, title, welcome message, placeholder, mobile visibility, delay, auto‑open.
Lead Form	Which fields to collect, service options, require phone, thank you message.
Notifications	Email notifications, email subject, include transcript, review link and text.
Integrations	Webhook URL and secret, default location ID.

Additional admin pages include Documentation and Tools (settings import/export).

8. Front-end Behaviour

• The floating widget appears on every public page (subject to your “show on mobile” setting).
• Each visitor gets an anonymous session id stored in a cookie / localStorage so their conversation persists.
• The bot decides when to show the lead form:
  • If the visitor mentions emergency keywords (for example “leak”, “burst”, “flood”), the form is shown.
  • If the chat happens after hours, the form is shown instead of continuing the conversation.
  • If Gemini returns errors or quota issues, the plugin offers the lead form as a fallback.
• All conversations are stored in the localbot_messages table and linked to leads when the form is submitted.
• On lead submit, the plugin stores traffic attribution metadata (source URL, referrer URL, and UTM fields) in lead metadata.
• If GDPR consent is enabled in settings, visitors must check the consent box before the lead can be submitted.

9. Tools (Import / Export)

• Go to LocalBot AI → Tools.
• Export Settings JSON downloads your current plugin configuration.
• Import Settings lets you restore configuration from a previous export file.
• Security hardening: exported files exclude API keys and webhook secrets by default.
• Security policy: store exported files only in secure internal storage.
• This is useful for moving settings between staging and production sites.

10. Improving AI Replies

• Keep replies short and focused on qualifying the lead (name, phone, service type, zip code, timing).
• Avoid very open‑ended prompts. Instead, tell the model exactly what to do:

  Ask friendly, short questions. Never give medical, legal, or financial advice.
  If the visitor is in an emergency, immediately ask for their phone and address.

• Use your FAQ / Knowledge field to paste key information about your services, pricing ranges, and process.

11. Database Tables

Table	Purpose
wp_localbot_leads	Stores leads, status, urgency, and metadata.
wp_localbot_messages	Chat messages per session (user & assistant).
wp_localbot_analytics_daily	Daily aggregates for chats, leads, errors, tokens.
wp_localbot_logs	System logs (errors, webhooks, rate limits).
wp_localbot_locations	Locations for multi‑location setups.

12. Uninstall

When you delete the plugin from Plugins → Installed Plugins, the uninstall routine will:

• Drop all localbot_* custom tables listed above.
• Delete plugin options prefixed with localbot_pro_.

Use this only on staging or when you are sure you no longer need the stored leads and transcripts.

13. Troubleshooting

• Widget does not appear
  • Check that the plugin is activated.
  • Ensure you are not blocking the script with a caching / optimization plugin.
• Bot says “busy” or leads form appears too often
  • Check Settings → API for 429 / quota errors.
  • Lower the per‑IP rate limit if you are testing heavily from a single IP.
• Time‑based behaviour is wrong (after hours vs open)
  • Verify your Timezone and the “Current time in this timezone” string in Settings → General.
  • Confirm that business hours are correct and in 24‑hour format.
• No emails received
  • Check Settings → Notifications for the recipient email.
  • Verify that your host can send emails (test with a basic contact form).

14. Translation

The plugin is fully translation‑ready:

• Text domain: localbot-ai.
• Language files are located in wp-content/plugins/localbot-ai/languages/.
• You can use tools like Poedit or Loco Translate to create translations.

If you run into issues, please contact support via your Envato downloads page with as much detail as possible (screenshots, error logs, and steps to reproduce).