Operator & Business Owner Guide

Before You Start: This Is Not a Magic Wand

HighVibe Agents is a decision and operations platform, not a replacement for your sales team, site foreman, or customer follow-up discipline. When configured correctly and used with a consistent daily workflow, it helps you capture leads, prioritize conversations, and keep an audit trail of AI-assisted decisions. It does not automatically close deals, install flooring, or guarantee revenue.

Treat AI responses as drafts and signals, not final commitments. Pricing, warranty terms, payment plans, legal wording, and installation timelines must pass through your approval queue or be written manually by a qualified person on your team.

• Follow-up: Check Operations Center at least once per business day.
• Tracking: Keep conversation states and next actions current — stale data produces weak KPIs.
• Accountability: Action logs exist so you can see who approved what and when.
• Limits: ROI and forecast charts are models based on your data quality; they are guides, not promises.

If you follow the workflows in this guide, most tenants see clearer visibility within the first two weeks. Revenue impact depends on your offer, market, and response speed — not on the logo on the login screen.

Welcome and How to Use This Guide

Thank you for choosing HighVibe Agents. This guide is written for business owners and daily operators who use the Operations Center at /app/. It describes what the product actually does today — without marketing exaggeration.

Recommended reading order:

1. Philosophy and roles (sections 1–3)
2. Daily workflow and dashboard (sections 4–6)
3. Inbox, approvals, and KPI center (sections 7–13)
4. Channels: web widget and WhatsApp (sections 14–16)
5. Compliance, language, and AI settings (sections 17–19)
6. Sector modules and CRM basics (sections 20–22)
7. Best practices, troubleshooting, glossary (sections 23–25)

Use the table of contents on the left to jump to any section. Switch language with the TR / EN pill in the page header. Your tenant default locale is set in admin under primary_locale.

• Operations Center — your home base
• Login — tenant user credentials
• Privacy notice — text shown to end customers

Roles: Owner, Operator, and Viewer

Each person on your team should have the right access level. Over-permissioning creates accidental approvals; under-permissioning blocks daily work.

Superusers (platform staff) can switch tenants from the top bar. If you see the wrong company name in the header, select the correct tenant before approving anything.

Login and Navigation

Login URL: /login/

After login you land on the Operations Center (/app/). Main navigation:

Language switcher in the top-right changes UI labels (EN, TR, DE, FR, ES, AR supported in the panel).

Recommended Daily Operations Workflow

Consistency beats intensity. If you follow this loop on working days, the platform stays trustworthy.

1. Open Operations Center — note open conversations, pending approvals, and ROI snapshot age.
2. Check Approval Queue first — pricing, warranty, and payment recommendations should not wait.
3. Work the Inbox — sort by handoff or urgency; reply to customers; update states.
4. Refresh KPI Report (if data changed materially) — review decision recommendations.
5. End of day — set next_action on open conversations so tomorrow starts clear.

Operations Center Dashboard

The dashboard at /app/ is your at-a-glance control room. Metrics refresh from the latest analytics snapshot (auto-refreshed if older than ~15 minutes).

Top metric cards

Embedded 3D preview

Two mini charts — Lead Intelligence 3D and Decision Surface 3D — mirror the full KPI page. Use Full Report & Actions for the complete deck.

Recommended Decisions panel

Shows the five newest decision recommendations with priority, confidence, and quick links to KPI or Approval Queue. Empty here does not mean "no work" — check inbox for unrouted messages.

Recent Action Logs

Audit trail of automated and human actions (approval queue, inbox updates, webhooks). Use this when asking "who approved this quote draft?"

Conversation Inbox

The inbox at /app/inbox/ lists all conversations for your tenant, newest first.

Filters

• Search (q): Matches summary, next action, external ID, lead name/phone/email, customer fields.
• State: new, contacted, engaged, qualified, offer, negotiation, won, lost.
• Channel: webchat, whatsapp, telegram, email, call, manual.
• Handoff: Show only conversations flagged handoff_required.

Summary counters

Recent messages sidebar shows the latest twelve inbound/outbound lines across conversations — useful for spotting duplicate threads from the same phone number.

Conversation States and AI Scores

Each conversation has a state, optional scores, and a handoff flag.

State progression (typical)

Scores (0–100 scale, model-dependent)

• urgency_score — time sensitivity (e.g. broken boiler vs browsing tiles)
• qualification_score — budget/fit signal strength
• sentiment_score — tone of recent messages

Scores help prioritize inbox sorting; they are not credit scores or legal assessments. When in doubt, read the message thread.

Conversation Detail and Timeline

Open any row in the inbox to reach /app/inbox/<id>/. You see the full message timeline, linked lead, recommendations for that lead, and action logs for the thread.

Manual updates (POST form)

• Note: Add inbound, outbound, or system message to the timeline.
• State: Move the conversation along the funnel.
• Next action: Short text reminder (max 255 chars) visible on dashboard lists.
• Handoff required: Checkbox — surfaces in Approval Queue and inbox filter.

Every save creates an ActionExecutionLog entry with provider conversation_inbox so manual edits are auditable.

Sibling conversations

Same customer may have multiple channels (web then WhatsApp). Review siblings before duplicating quotes.

Approval Queue and Human Handoff

The approval queue at /app/approvals/ is where human judgment is mandatory. Low-risk informational replies may flow automatically; high-risk business commitments do not.

What requires approval (examples)

• Firm price quotes beyond configured thresholds
• Payment terms, deposits, and installment promises
• Warranty length or scope guarantees
• Legal or compliance statements
• Discounts that affect margin

Queue sections

Approve / Reject workflow

1. Read title, summary, and recommended_action carefully.
2. Click Approve or Reject (or Executed for specific marketing actions on KPI page).
3. System updates recommendation status, clears handoff when applicable, writes ConversationMessage system note, logs ActionExecutionLog.

Decision Recommendations Explained

DecisionRecommendation records are AI-generated action proposals tied to your tenant, often linked to a lead and analytics snapshot. They appear on the dashboard, KPI page, and approval queue.

Status lifecycle

1. Created after KPI refresh or inbound webhook processing
2. Stays pending until a logged-in operator decides
3. Approved/rejected/executed — immutable for audit; create a new conversation note if plan changes

If recommendations pile up without review, automation_score rises in KPIs but real workload also rises. Clear the queue regularly.

KPI and Action Center Overview

The Executive KPI & Action Center at /app/analytics/ combines metrics, charts, and actionable recommendations in one screen.

Header actions

• Refresh KPI Report — rebuilds analytics snapshot (?refresh=1); use after bulk imports or end-of-week review.
• Links back to Dashboard and Approval Queue.

Top KPI cards

Snapshot timestamp and model name (from TenantAISettings) appear in badges — if snapshot is stale, refresh before a management meeting.

KPI Charts: Full Chart Deck Reference

When you refresh the KPI report, the platform builds a chart_pack JSON used by Plotly charts below. Each chart is only as accurate as your CRM data (leads, orders, invoices, conversations).

3D Analytics Command View

High-Value Customer (HVC) Segment Engine

Deterministic segmentation over customers and revenue — shows HVC count, revenue share, average score, and top signal customer. Methodology confidence badge reflects data completeness, not market certainty.

Standard charts

Underlying KPI payload fields

• lead_count, customer_count, conversation_count
• conversion_rate, engagement_rate
• data_quality_score, automation_score, forecast_accuracy
• avg_order, paid_revenue, pipeline_revenue, qualified_leads, won_leads
• hvc_count, hvc_revenue_share, avg_hvc_score (when HVC engine runs)

Worked Example: Osman Çavuş Taş Parke (parke_tas)

This section walks through a real pilot pattern — stone and parquet flooring contractor — using niche parke_tas and tenant slug osman-cavus-tas-parke. Names and numbers are illustrative; your quotes and m² rates must come from your own price list.

Day 0 — go-live checklist (operator view)

1. Owner logs in at /login/ — user e.g. talha linked as TenantUser owner.
2. Confirm tenant status active and chat_widget_enabled is true.
3. Greeting text set in Turkish: "Hoş geldiniz! Metrekare, taş türü ve lokasyon yazarsanız keşif yönlendirmesi yapabilirim."
4. Widget embedded on customer website; test at /widget/demo/osman-cavus-tas-parke/.
5. WhatsApp webhook configured with scoped TenantAPIKey (platform team) — optional but recommended.

Scenario A — Web widget lead (villa owner, Yalova)

Customer message: "200 m² villa bahçesi, gri granit istiyorum, rough budget?"

1. Widget creates Lead + Conversation (channel webchat, state new).
2. AI responds with clarifying questions: sub-base condition, drainage, edge finishing, access for pallet truck.
3. Operator reviews inbox within 2 hours — sets state engaged, adds system note: "Site visit Tue 10:00 — Talha."
4. AI may draft m² range using catalog hints (begonit/granite) — if numeric quote appears, it lands in Approval Queue.
5. Owner approves or edits: rejects AI quote if fire allowance (waste %) for diagonal cut was ignored.
6. After site visit, operator sets qualified, next_action "Send written quote PDF".

Scenario B — WhatsApp urgent (contractor, material list)

Customer message: "800 m² kilit parke 8 cm, 2 haftada teslim — stok var mı?"

1. Webhook ingests message; idempotent by provider message ID.
2. Conversation channel whatsapp; urgency_score likely high due to volume + deadline words.
3. Handoff_required set if AI cannot confirm stock — operator calls supplier, logs outbound note with availability.
4. Decision recommendation may suggest "prioritize B2B quote" — approve only if capacity real.

Scenario C — Lost deal (learning loop)

Customer chose competitor on price. Operator sets state lost, system note reason "competitor −12% on labor only".

Next KPI refresh includes lost stage in funnel — use for retrospective, not blame.

What Osman should not expect from AI

• Automatic structural engineering sign-off for load-bearing terraces
• Guaranteed delivery dates without warehouse integration
• Binding m² prices without human approval when margins are tight
• Replacement for on-site moisture / sub-base inspection

Web Chat Widget Installation

The chat widget captures leads from your public website into the same inbox as other channels.

Embed snippet

<script src="https://YOUR_DOMAIN/widget.js"
  data-tenant-slug="YOUR_TENANT_SLUG"
  data-lang="tr"
  async></script>

YOUR_TENANT_SLUG must match the tenant slug in admin exactly (e.g. osman-cavus-tas-parke).

Preview and test

• Demo page: /widget/demo/YOUR_TENANT_SLUG/
• Send a test message; confirm it appears in inbox within seconds.
• Check lead record for KVKK consent metadata if privacy banner enabled.

WhatsApp Channel

WhatsApp messages arrive via the inbound webhook /api/webhooks/whatsapp/ using a scoped TenantAPIKey. Setup is typically done by platform staff — operators verify results in the inbox.

Operator verification steps

1. Send a test message from your phone to the connected business number.
2. Confirm new Conversation with channel whatsapp and matching lead phone.
3. Check DataImportJob completed (admin view) if messages missing — failed jobs mean config issue.
4. Reply from your normal WhatsApp Business app; log important calls as manual inbound notes if needed.

Behavior notes

• Webhook is idempotent — duplicate Meta delivery does not duplicate leads when message ID repeats.
• High urgency keywords may increase urgency_score and trigger handoff.
• Rate limits apply per API key — burst campaigns on same key may temporarily fail.

Leads, Stages, and Scoring

Every conversation links to a Lead record when possible. Leads carry CRM stage, source, and consent fields.

Lead stages

Sources

webchat, whatsapp, manual, import, referral — filter in admin/reports by source to measure channel ROI.

Scoring alignment

Conversation qualification_score and lead stage should move together. If AI scores high but stage stays new for a week, dashboard conversion metrics lie kindly.

Privacy, KVKK, and Consent

End customers see your privacy notice at /kvkk/. Widget and public demo forms record consent version on the lead when configured.

• Do not paste full ID numbers or health data into chat — AI logs messages in tenant database.
• Privacy profile (masked/local/regional) is set at platform level — operators see effects, not raw keys.
• Export/delete requests for end customers are handled by your business process; platform owner assists on tenant data export.

Language and Locale

Panel UI language is switched from the header (EN/TR/DE/FR/ES/AR). Tenant primary_locale drives default widget language and some chart label refresh on analytics snapshots.

• Guide pages: ?lang=en or ?lang=tr query parameter.
• Widget: data-lang attribute on script tag.
• Mixed-language customers: AI often detects Turkish/English mix; operator notes clarify contract language.

AI Settings (Operator View)

Operators usually cannot change LLM provider or monthly budget — those live in TenantAISettings (admin). You should know how settings affect daily behavior.

Sector Modules and Niches

ModuleConfig enables vertical features per tenant sector. Niche persona shapes AI tone and catalog hints.

Modules appear in admin and some list views (/products/, /customers/, /orders/, /repair-requests/) when enabled. Empty modules mean no data yet — not a broken install.

MSP Module (IT Providers) — Operator Summary

If your tenant is an IT managed service provider, additional msp_core objects exist: Clients, Sites, Devices, Tickets, SLA policies, Contracts, Time entries. Flooring/construction tenants typically ignore this section.

AI triage (ARIA) for MSP tickets is evolving — when enabled, recommendations appear like other decision rows. Human approval still applies to customer-facing commitments.

API Keys and Integrations (Overview)

TenantAPIKey enables scoped programmatic access (imports, webhooks, external CRM). Operators rarely create keys; know what exists to avoid sharing secrets in chat.

• Keys shown once at creation — store in password manager.
• Scopes limit blast radius (e.g. whatsapp webhook only).
• Rotate key if employee leaves or key pasted in ticket by mistake.

Conversion Tracking and Attribution

ConversionEvent records (when module enabled) support ad attribution to Google/Meta/TikTok with hashed PII — used for marketing ROI outside the KPI snapshot.

• Landing page demo form may create leads with UTM parameters.
• Align ad campaign names with lead source field for cleaner reports.
• Attribution does not replace invoice-based revenue in KPI ROI gauge.

CRM Basics: Products, Customers, Orders

Beyond conversations, core CRM lists help quotes and KPI revenue charts.

Data quality_score on KPI rises with more structured records — garbage in, decorative charts out.

Best Practices for Operators

1. Same-day first response on web/WhatsApp — even if full quote takes days.
2. One owner per conversation — assign_user when feature used; avoids duplicate calls.
3. Reject bad AI quotes fast — trains your team rhythm; model retrain is platform-side.
4. Weekly KPI refresh in team meeting — look at funnel, not only lead count.
5. Document wins and losses in system notes — improves retrospective accuracy.
6. Keep greeting and niche aligned with actual services you sell.
7. Test widget after every website deploy — CMS changes break script tags silently.

Troubleshooting Common Issues

Before opening a support ticket, capture: tenant slug, conversation ID, screenshot, approximate time (timezone), and whether issue affects all users or one channel.

Action Logs and Audit Trail

Every meaningful event — webhook ingest, approval decision, inbox edit, automated triage — can create an ActionExecutionLog row. Operators use logs to answer accountability questions without guessing.

Common providers seen in logs

Fields worth reading

• action_type — categorizes the business action (human_handoff, pricing, etc.)
• status — completed, failed, pending
• decision_summary — one-line human-readable outcome
• input_excerpt / output_excerpt — truncated message fragments for quick review
• payload — JSON with IDs (conversation_id, recommendation_id) for support tickets

On the dashboard, recent five logs give a pulse; Approval Queue shows fifty. For disputes older than that, contact your platform owner with date range and lead name.

Practical audit scenarios

1. Customer denies quoted price: Search logs for approval_queue on that date; compare recommended_action to sent PDF.
2. Duplicate WhatsApp message: Check whatsapp_webhook entries — idempotent replay shows completed without second lead.
3. Operator handover: New shift reads conversation_inbox logs to see what prior shift promised.

Public Landing Page and Demo Requests

Some tenants expose a public landing page with embedded charts and a demo request form. Operators may not edit layout, but should know leads can arrive from there as well as widget/WhatsApp.

Demo request flow

1. Visitor submits name, contact, message on public home.
2. System creates Lead with source metadata and KVKK consent when checkbox used.
3. Lead appears in CRM; conversation may start as manual or web channel depending on configuration.
4. Operator follows same inbox workflow — first response wins trust.

Operator checklist for landing leads

• Respond within one business day even if AI already sent an auto-acknowledgment.
• Verify phone format — international numbers may need manual normalization before WhatsApp outreach.
• Set realistic next_action — "Call back" with date beats empty field.

Landing page is not a substitute for your corporate website. Most construction pilots embed widget on their existing WordPress or static site instead.

Team Handovers and Shift Notes

Multi-operator teams fail when shift changes hide context. HighVibe does not replace a CRM task board — but disciplined use of system notes and next_action fields replaces sticky notes on monitors.

End-of-shift template (system note)

SHIFT 2026-06-06 eve | Operator: NAME
Open: Conv #123 waiting site visit confirm; Conv #456 WhatsApp price pending approval
Blocked: None / Budget approval from owner
Next shift: Call Conv #123 before 10:00

Assignment

When assigned_user is set on a conversation (admin or detail view), filter inbox informally by searching assignee name in admin exports — UI assignee filter may expand in future releases.

Glossary

When terminology in the panel differs from this glossary, trust the on-screen label — product copy updates faster than PDF exports.