AI Buddy Overview

Nimbly AI Buddy — Project Overview

What is Nimbly AI Buddy?

Nimbly AI Buddy is a WhatsApp-based AI chatbot that connects to the Nimbly operational platform. Instead of logging into dashboards or navigating complex admin panels, users simply send a WhatsApp message in their own language and get instant insights about reports, issues, and site information. It understands natural language, remembers conversation context, and supports 10 languages out of the box.

---

How It Works (High-Level)

flowchart TD
    A[You send a WhatsApp message] --> B[Nimbly AI Buddy receives it]
    B --> C["Understands what you're asking about\n(reports? issues? sites?)"]
    C --> D[Extracts any dates, site names, or filters]
    D --> E[Fetches real data from the Nimbly Platform]
    E --> F[Formats a clean, readable response]
    F --> G[Sends it back to you on WhatsApp]

The entire round-trip typically takes a few seconds. You ask in plain language, and you get real data back — no dashboards, no logins, no navigation.

---

Getting Started

Step 1: Send Your First Message

Send any message (even just “Hi”) to the Nimbly AI Buddy WhatsApp number. Since you don’t have an active session yet, you’ll receive a message with a login button.

Step 2: Log In

Click the “Open Authentication Link” button. This opens a login page in your browser where you enter your Nimbly credentials (email/username + password). The login link is valid for 15 minutes and can only be used once.

If your link expires, just send another message to the chatbot — you’ll get a fresh link.

Step 3: Start Chatting

After logging in, you’re redirected back to WhatsApp and receive a welcome message with interactive buttons:

✅ Login Successful

You’re now logged in and ready to use Nimbly AI Buddy. Ask me anything about your reports, issues, or site information!

⚠️ AI can make mistakes—please double-check important info.

Buttons: How to Use | Quick Actions | Account & Settings

From here, tap a button or just type your questions naturally.

First-Time Access

When an admin grants you access to Nimbly AI Buddy, you receive a welcome message:

👋 Hi [Your Name], you now have access to Nimbly’s AI Buddy!

I’m your intelligent assistant for accessing operational data quickly using natural language.

I can help you with:

• Issues & tickets tracking
• Report completion & metrics
• Site details & team info

Quick commands: /help, /start

Send me any message to get started!

Session Duration

Your session stays active for 30 days. Every time you send a message, the timer resets. If you go 30 days without using the chatbot, you’ll need to log in again.

Conversation memory resets after 3 hours of inactivity — if you come back after a break, the bot starts fresh but your session remains active (no need to log in again).

If your session expires mid-conversation, you’ll see: “Your session has expired. Please log in again to continue using the chatbot.” — followed by a new login link.

---

What You Can Ask

Report Queries

Ask about report completion, compliance rates, and performance metrics.

Example questions:

• “What were the KPIs for last week?”
• “How many reports were missed yesterday?”
• “Show me the RCR (Report Compliance Rate) for this month”
• “Which department has the most missed reports?”
• “Give me the report completion breakdown by site for last week”
• “What’s the trend of completed reports this month?”
• “How long are reports taking to complete on average?”

What you can filter by:

• Site name — “What’s the RCR for Forum Mall?”
• Department — “Show missed reports by department”
• User — “How many reports did Ahmad complete last week?”
• Questionnaire — “Show completion for the Daily Store Audit”
• Time period — “last week”, “yesterday”, “this month”, “March 2025”

Issue Queries

Ask about issues, resolution rates, and problem areas.

Example questions:

• “What is this month’s IRR (Issue Resolution Rate)?”
• “How many open issues do we have?” (includes open + in-progress + in-review)
• “Which sites had the most issues last week?”
• “What’s the daily issue trend for this week?”
• “Show me unresolved issues by department”
• “What’s the average resolution time?”
• “Give me a breakdown of issues by flag category”

Same filters apply — site, department, user, questionnaire, and time period.

Site & Lookup Queries

Ask about locations, people, and questionnaires.

Example questions:

• “Find the site ID for Warehouse 5”
• “Look up user John Smith”
• “What’s the ID for the Safety Checklist questionnaire?”

The bot searches the Nimbly platform and returns matching results. If multiple matches are found, it shows you the top results and asks which one you meant.

Out-of-Scope Questions

If you ask something unrelated (e.g., “What’s the weather?”), the bot politely responds:

“I can only help with reports, issues, or site information.”

If your question is vague, it asks for clarification:

“Could you be more specific? Are you asking about reports, issues, or site information?”

These messages are localized to your language.

---

Quick Actions & Commands

Prompt Shortcuts (1–5)

Type a single number to instantly run a pre-built query:

Type	What It Does
1	”What were the KPIs for last week?“
2	”What is this month’s issue resolution rate (IRR)?“
3	”Give me missed reports and schedules for yesterday.”
4	”Which sites had the highest number of issues last week?“
5	”What is the daily issue trend for this week?”

You can also use emoji keycaps (1️⃣, 2️⃣, etc.) — they work the same way.

Commands

Command	What It Does
help	Shows a menu with “How to Use”, “Quick Actions”, and “Account & Settings”
start or prompt	Shows the welcome greeting with quick action buttons
quick actions	Opens the numbered list of prompt shortcuts
how to use	Shows example questions and usage tips
clear	Clears conversation history (keeps you logged in)
logout	Ends your session — send any message to log in again
account & settings	Shows account management options (Clear / Logout)

Commands are case-insensitive — “Help”, “help”, and “HELP” all work. No slash needed.

Interactive Buttons

Many responses include tappable WhatsApp buttons. For example, after a greeting or help command, you’ll see:

• How to Use — Shows example questions and a tip

• Quick Actions — Opens a scrollable list of the 5 prompt shortcuts

• Account & Settings — Shows options to Clear history or Logout

The Account & Settings menu gives you two buttons:

• Clear — Same as typing “clear”
• Logout — Same as typing “logout”

Processing Indicator

When you ask a report, issue, or site question, the bot sends a quick acknowledgment: “Your request is being processed.” (in your language) — so you know it’s working on it.

---

Language Support

Nimbly AI Buddy supports 10 languages with automatic detection:

Language	Greetings Recognized
English	hi, hello, hey, good morning, good evening
Indonesian	hai, halo, selamat pagi, selamat siang
Malay	hai, halo, assalamualaikum
Spanish	hola, buenos dias, buenas tardes
Portuguese	oi, ola, bom dia, boa tarde
Thai	สวัสดี, sawasdee
Korean	안녕하세요
Vietnamese	xin chao
Chinese	你好, 您好
Japanese	こんにちは

How it works:

• The bot detects your language automatically from each message
• Responses come back in the same language you wrote in
• You can switch languages mid-conversation — the bot adapts instantly
• Greetings, help messages, error messages, and processing indicators are all localized

Smart greeting detection: If you write “Hi, what were last week’s KPIs?”, the bot treats it as a query — not a greeting. It only shows the greeting screen when your message is purely a greeting.

---

Smart Features

Natural Date Understanding

You don’t need to type exact dates. The bot understands natural language time references in any supported language:

• “last week”, “yesterday”, “this month”, “last 3 months”
• “minggu lalu” (Indonesian for “last week”)
• Thai Buddhist Era dates (2568 → 2025)
• Slang and typos: “lst wk” → last week

If the bot can’t figure out the time period, it asks you: “What time period would you like me to check?”

Follow-Up Conversations

The bot remembers context within a conversation. You can ask follow-up questions naturally:

You: “What were last week’s KPIs?” Bot: (shows KPI data) You: “What about last month?” Bot: (shows same KPIs but for last month — no need to repeat the full question)

Short follow-ups like “same”, “also”, “and for last month?”, “yes”, “continue” are all understood.

Smart Name Resolution

When you mention a site, person, or questionnaire by name, the bot automatically searches the Nimbly platform to find the right match:

• “Show me reports for Warehouse 5” → finds the site ID automatically
• “How many reports did Ahmad complete?” → finds the user ID automatically
• “Completion rate for the Daily Store Audit” → finds the questionnaire ID automatically

If there are multiple matches, the bot shows you the options and asks which one you meant.

Conversation Memory

• The bot keeps context for your current conversation session
• After 3 hours of inactivity, memory resets (fresh start)
• Type clear anytime to manually reset the conversation
• Long conversations (40+ messages) are automatically summarized to stay within limits — the bot keeps the last 6 messages and condenses older ones into a summary

Response Formatting

All responses are optimized for WhatsApp:

• Bold text highlights key metrics and numbers
• Bullet points for readable breakdowns
• Organized sections (by site, department, user, trend)
• Date ranges always included for context (e.g., “For the week of March 1–7, 2025”)
• A link to the Nimbly admin portal is appended to data responses, so you can dive deeper into dashboards and exports

---

Typical Conversation Example

Here’s what a real conversation looks like:

You:   Hi
Bot:   👋 Hello! I'm Nimbly's AI Buddy. Ask me about reports,
       issues, or site information.
       [How to Use] [Quick Actions] [Account & Settings]

You:   What were last week's KPIs?
Bot:   Your request is being processed.
Bot:   Here are your KPIs for last week (Feb 24 – Mar 2, 2025):

       *Report Compliance Rate (RCR):* 87.5%
       *Completed:* 420
       *Missed:* 60
       *Pending:* 15
       *Scheduled:* 480
       *Ad-hoc:* 15

       For detailed dashboards and exports, visit:
       https://admin.hellonimbly.com/login

You:   What about Forum Mall specifically?
Bot:   Your request is being processed.
Bot:   KPIs for *Forum Mall* last week (Feb 24 – Mar 2, 2025):

       *RCR:* 92.3%
       *Completed:* 36
       *Missed:* 3
       ...

You:   And the issues?
Bot:   Your request is being processed.
Bot:   Issue metrics for *Forum Mall* last week:

       *IRR (Issue Resolution Rate):* 78.6%
       *Open Issues:* 12
       *Resolved:* 44
       ...

You:   clear
Bot:   🗑️ Your conversation history has been cleared.
       Starting fresh!

Notice how the bot:

• Remembers “last week” and “Forum Mall” across follow-ups
• Switches from reports to issues while keeping the same filters
• Sends a processing indicator before fetching data

---

How It Works Under the Hood

The Agent System

Behind the scenes, the chatbot uses a multi-agent AI system. Think of it as a team of specialized assistants:

1. Intent Classifier — First, your message is analyzed to determine what you’re asking about (reports, issues, sites, or something else). This happens in milliseconds using pattern matching and AI classification.

2. Orchestrator Agents — Based on your intent, the message is handed to either the Report Agent or Issue Agent. These act as managers that understand your question and decide which specialist to call.

3. Specialist Agents — The orchestrators delegate to specialists:

   • KPI Agent — Handles simple metrics (totals, rates, counts)
   • Dashboard Agent — Handles detailed breakdowns (by site, department, trends, comparisons)

4. Site Agent — Handles location and lookup queries directly.

The Routing System

The intent classifier uses a 4-layer approach to understand your message:

1. Pattern matching — Fast keyword detection (instant)
2. AI classification — LLM analyzes the message meaning
3. Context analysis — Checks conversation history for follow-ups
4. Fallback — Uses your previous intent if nothing else matches

This layered approach means the bot is both fast (pattern matching catches obvious queries) and smart (AI handles nuanced or ambiguous questions).

Data Flow

When you ask a question, here’s what happens:

1. WhatsApp delivers your message via webhook
2. Session check — Verifies you’re logged in and authorized
3. Parallel processing — Intent classification and date extraction happen at the same time
4. Agent execution — The right agent processes your query, calling Nimbly Platform APIs to fetch real data
5. Response formatting — AI response is cleaned up for WhatsApp (markdown converted, unnecessary tags removed)
6. Delivery — Formatted response sent back to your WhatsApp

---

System Architecture

flowchart TD
    A[WhatsApp User] --> B["Whapi.Cloud\n(WhatsApp API)"]
    B <--> C["Login Page\n(Web browser)"]
    B --> D["Express Server\n(Webhook)"]
    D --> E[Intent Router]
    D --> F[AI Date Extract]
    E --> G[AI Agents]
    subgraph G[AI Agents]
        G1[Report Agent]
        G2[Issue Agent]
        G3[Site Agent]
    end
    G --> H["Nimbly Platform API\n(Real data)"]
    H --> I[Format & Send via WhatsApp]

---

Tech Stack

Component	Technology
Runtime	Node.js 20, TypeScript
Server	Express.js
AI Framework	Mastra.ai (multi-agent orchestration)
LLM Models	GLM-4, LLaMA-3.3 (via Parasail API)
Database	PostgreSQL (Supabase)
ORM	Drizzle
WhatsApp	Whapi.Cloud (webhooks + messaging API)
Authentication	Supabase Auth + JWT
Encryption	AES-256-GCM (for stored tokens)
Deployment	Docker, Google Cloud Functions, AWS ECS

---

Database Tables

Table	Purpose
user_chatbot_access	User accounts, permissions, and WhatsApp number mapping
user_sessions	Active sessions with encrypted tokens, conversation state, and preferences
login_tokens	One-time login links (15-minute TTL)
Mastra memory tables	Conversation history, thread summaries, and working memory

---

Key APIs Called

The chatbot fetches real data from the Nimbly Platform through these endpoints:

What	Endpoint
Report KPIs	/v1.0/statistics/dashboard/report/detail
Report Dashboard	/v1.0/statistics/dashboard/report/detailed
Issue KPIs	/v1.0/statistics/dashboard/issue/detail
Issue Dashboard	/v1.0/statistics/dashboard/issue/detailed
Platform Stats	/v1.0/statistics/dashboard/home-page-metrics
Site Search	Site name resolution API
User Search	User name resolution API
Questionnaire Search	Questionnaire name resolution API

---

Security

• Encrypted tokens — Platform authentication tokens are stored encrypted (AES-256-GCM) in the database, never in plain text
• Session management — 30-day TTL with automatic expiration, soft-delete on logout
• One-time login links — Each link expires after 15 minutes and can only be used once
• Content safety — AI responses are filtered for inappropriate content before sending
• No data storage — The chatbot doesn’t store your Nimbly data; it fetches it in real-time from the platform API and returns it directly