COS-INQ-001
WhatsApp Inquiry Intake & Job Creation
Purpose
When a customer sends a message on their dedicated WhatsApp group, the system must automatically:
- Create a Job with a unique ID (
CJ-2026-NNNNNN) - Parse the message into a structured brief using AI
- Store all reference images
- Surface the job in the assigned RM's queue
All of this happens before any human touches it. The RM's first interaction is reviewing a pre-parsed job, not reading a raw WhatsApp message.
Actors
| Actor | Type | Role |
|---|---|---|
| Customer | External | Sends the inquiry via WhatsApp |
| WhatsApp Cloud API | System | Delivers message via webhook |
| AI Intake Engine | System | Parses message into structured brief |
| AI Clarification Bot | System | Asks follow-up questions if brief is incomplete |
| RM (Rupsa / Rumi / Trishna) | Internal | Receives job in queue — reviews, does not re-enter data |
Trigger
POST /webhooks/whatsapp fires when any message arrives on a monitored WhatsApp group number.
Full Flow
1. Webhook received from WhatsApp Cloud API
→ Validate signature (x-hub-signature-256)
→ Return HTTP 200 immediately (WA requires fast ack)
→ Push to async processing queue
2. Identify sender
→ Match WA number to clients table
→ If unknown: create draft client record, flag for RM
(job still created — don't block intake)
3. Determine message type and pre-process
→ Text only → proceed
→ Image(s) → upload to S3: jobs/<job_id>/refs/imgN.jpg
→ Voice note → send to Whisper API → transcript → treat as text
→ Mixed → all handled, all linked to same job
4. Session grouping check
→ Is there an OPEN job for this customer from the last 30 minutes?
YES → append communication, do not create new job
NO → create new job record (CJ-YYYY-NNNNNN)
5. Create records
→ job { job_id, client_id, client_manager_id, intake_channel: whatsapp,
current_state: DRAFT, ... }
→ job_event { event_type: job.created, actor: system }
→ job_communication { direction: inbound, raw_text, channel: whatsapp }
→ job_file per image { kind: ref, s3_url, version: 1 }
6. Send to AI Intake Engine
→ Input: message text (or transcript) + image S3 URLs
→ Output: brief_structured JSON
7. Evaluate confidence
→ >= 0.75 → set state: BRIEF_CONFIRMED
→ < 0.75 → set state: INTAKE_PARSED
→ trigger AI Clarification Bot on same WA thread
→ wait for reply → re-parse → re-evaluate
8. Job surfaces in RM's queue
→ Push notification to RM's device
→ Job card visible in RM queue appAI Intake Engine — Output Schema
{
"category": "hiphop | bridal | cuban | custom",
"sub_category": "pendant | ring | chain | bracelet | earring | bangle",
"metal": {
"type": "gold | silver | platinum",
"karat": "10 | 14 | 18 | null",
"tone": ["yellow", "white", "rose"]
},
"stones": {
"type": "natural | lab_grown | gemstone | moissanite",
"shapes": ["round", "baguette", "princess", "fancy"],
"setting": "bussdown | prong | bezel | pave | channel | null",
"color": null,
"clarity": null
},
"dimensions": {
"budget_usd": null,
"weight_g_approx": null,
"size": null,
"length_in": null,
"thickness_mm": null
},
"attachments": {
"chain_type": null,
"bail": null,
"finding": null
},
"special_instructions": "",
"deadline": null,
"deliverables_requested": ["pricing", "coral", "cad"],
"references": ["s3://chandra-jobs/CJ-2026-001234/refs/img_001.jpg"],
"ambiguities": ["karat not specified", "diamond quality not mentioned"],
"confidence": 0.86
}AI Clarification Bot
Fires when confidence < 0.75. Sends structured questions back on the same WhatsApp thread.
Sample Message
Hi [Name], just 2 quick questions on your inquiry:
1. What karat gold — 10kt, 14kt, or 18kt?
2. Natural diamonds or lab-grown?
Reply here and we'll get started right away.
— Chandra JewelsRules
- Max 3 questions per inquiry
- Ask only for fields that affect design or pricing (not cosmetic fields)
- If no reply within 2 hours → RM notified to follow up manually
- Bot replies are parsed and merged into
brief_structured - Bot messages stored in
job_communication(direction: outbound)
Data Model
job {
job_id "CJ-2026-001234" -- auto-increment, year-aware
client_id → clients
client_manager_id → users (assigned RM)
category from AI
sub_category from AI
intake_channel "whatsapp"
intake_raw_ref whatsapp_message_id
brief_structured JSONB (AI output)
current_state "BRIEF_CONFIRMED" | "INTAKE_PARSED"
priority_score float (initial compute)
created_at now()
}
job_event {
job_id "CJ-2026-001234"
event_type "job.created"
actor_id "system"
payload { source: "whatsapp", client_id: ... }
created_at now()
}
job_communication {
job_id "CJ-2026-001234"
channel "whatsapp"
direction "inbound"
sender customer WA number
raw_text message text or transcription
parsed_intent "new_inquiry"
created_at now()
}
job_file { -- one row per image
job_id "CJ-2026-001234"
kind "ref"
s3_url "s3://chandra-jobs/CJ-2026-001234/refs/img_001.jpg"
uploaded_by "system"
version 1
created_at now()
}Business Rules
| Rule | Detail |
|---|---|
| Session grouping | Messages within 30-min window on same thread → same Job. No duplicate jobs. |
| Follow-up messages | Customer replies to open Job thread → append job_communication, do not create new Job |
| Multiple designs in one message | AI detects 2+ distinct briefs → creates one Job per brief → RM confirms split |
| Voice note | Transcribed via Whisper before AI parsing. Original audio + transcript both stored. |
| File path | All files under s3://chandra-jobs/<job_id>/refs/<filename> |
| Job ID format | CJ-YYYY-NNNNNN — resets per year, zero-padded 6 digits |
| Unknown customer | Create draft client record. Job still created. RM completes client details. |
| Hindi messages | Whisper transcribes Hindi. AI parses translated text. Both stored in job_communication. |
Edge Cases
| Scenario | Handling |
|---|---|
| Customer sends image only, no text | Job created, confidence = 0.0, clarification bot fires immediately |
| Repeat order detected | AI flags. RM confirms: repeat → pricing; new → design |
| Customer sends follow-up to inquiry > 7 days old | Treat as new Job. Old job is CLOSED. |
| Multiple images from different angles | All stored as kind: ref. AI uses all for parsing. |
| Webhook delivery failure | Exponential backoff retry ×3. If all fail → email alert to RM. |
| PDF attachment | Stored in S3. Flagged for RM to read manually. Not AI-parsed in v1. |
| Customer in 2 RMs' lists | Not allowed. Admin config enforces 1 customer → 1 RM. |
API Endpoints
POST /webhooks/whatsapp
Receives WhatsApp Cloud API webhook
Validates x-hub-signature-256
Returns 200 immediately
Enqueues for async processing
POST /internal/jobs/create-from-whatsapp [internal, async]
Runs full intake flow (steps 2–8 above)
Returns { job_id, state, assigned_rm_id }
GET /jobs/:job_id
Full job record with brief, files, events, communications
POST /jobs/:job_id/communications
Append communication to existing job (used for follow-up messages)Wireframes — Mobile
Screen M1 — Push Notification (Lock Screen)
┌─────────────────────────────────────┐
│ 9:41 AM │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 🔔 Chandra OS now │ │
│ │ │ │
│ │ New inquiry — Icechamp │ │
│ │ Hip Hop Pendant · $8,000 │ │
│ │ Tap to review → │ │
│ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────┘Screen M2 — RM Queue (Home Screen)
┌─────────────────────────────────────┐
│ ← Rupsa's Queue [Filter] │
│ │
│ 3 NEW · 9 PENDING · 2 WAITING │
├─────────────────────────────────────┤
│ NEW │
├─────────────────────────────────────┤
│ ┌─────────────────────────────────┐ │
│ │ 🆕 CJ-2026-001234 14m ago │ │
│ │ │ │
│ │ Icechamp │ │
│ │ Hip Hop Pendant │ │
│ │ │ │
│ │ [img] $8,000 · 14kt WG │ │
│ │ Natural VVS diamonds │ │
│ │ │ │
│ │ ⚠ Karat unconfirmed │ │
│ │ │ │
│ │ [Route Now →] │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 🆕 CJ-2026-001233 31m ago │ │
│ │ Prime · Bridal Ring · $3,200 │ │
│ │ [img] 14kt Rose Gold │ │
│ │ [Route Now →] │ │
│ └─────────────────────────────────┘ │
│ │
│ PENDING ROUTING │
├─────────────────────────────────────┤
│ ┌─────────────────────────────────┐ │
│ │ ⏳ CJ-2026-001230 2h ago │ │
│ │ Icechamp · Cuban Chain │ │
│ │ Routed to CAD HipHop ✓ │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘Notes:
- 🆕 = new, needs routing action
- ⚠ = AI flagged ambiguity, shown inline
- ⏳ = already routed, just for monitoring
- SLA timer not shown on queue cards — shown inside job detail
Screen M3 — Job Detail (read-only, before routing)
┌─────────────────────────────────────┐
│ ← CJ-2026-001234 [⋮ More] │
├─────────────────────────────────────┤
│ Icechamp · Rupsa │
│ Received 14 min ago · ⚠ Route │
│ within 1h 46m │
├─────────────────────────────────────┤
│ │
│ ORIGINAL MESSAGE │
│ ┌───────────────────────────────┐ │
│ │ "Hi, need a pendant. Big │ │
│ │ bussdown, rose gold, around │ │
│ │ $8k. See ref attached." │ │
│ │ │ │
│ │ [img_001.jpg ▸] │ │
│ └───────────────────────────────┘ │
│ │
│ AI PARSED BRIEF │
│ ┌───────────────────────────────┐ │
│ │ Category Hip Hop Pendant │ │
│ │ Metal Rose Gold │ │
│ │ Karat ⚠ Not specified │ │
│ │ Budget $8,000 │ │
│ │ Stones Natural · Bussdown│ │
│ │ Deadline Not mentioned │ │
│ └───────────────────────────────┘ │
│ │
│ Est. gold weight 12g – 16g │
│ Est. diamonds 3.2ct – 4.0ct │
│ │
│ CUSTOMER NOTES │
│ ┌───────────────────────────────┐ │
│ │ Prefers 14kt. Last 8 orders │ │
│ │ all 14kt WG or RG. │ │
│ │ Avg budget $9,200. │ │
│ └───────────────────────────────┘ │
│ │
├─────────────────────────────────────┤
│ [Route to Design →] │
└─────────────────────────────────────┘Notes:
- Original message shown verbatim at top — RM sees exactly what customer sent
- AI parsed brief shown below — editable in COS-RTE-001 routing screen
- Estimated weight/carat range auto-computed from budget (Anmol's formula)
- CTA routes to COS-RTE-001 routing screen
Wireframes — Desktop
Screen D1 — RM Queue Dashboard
┌──────────────────────────────────────────────────────────────────────────────┐
│ CHANDRA OS [≡] Rupsa's Queue 🔔 3 [RP] Rupsa │
├────────────┬─────────────────────────────────────────────────────────────── │
│ │ │
│ ◉ My Queue│ MY QUEUE · 3 NEW · 9 PENDING · 2 SLA WARNING │
│ ○ All Jobs│ ───────────────────────────────────────────────────────── │
│ ○ Reports │ │
│ │ [ ] Select all Filter: [All ▾] Sort: [Newest ▾] │
│ ───── │ ───────────────────────────────────────────────────────── │
│ │ │
│ CUSTOMERS │ 🆕 NEW — NEEDS ROUTING │
│ Icechamp │ ┌───────────────────────────────────────────────────────────┐ │
│ Prime │ │ [img] CJ-2026-001234 · Icechamp · Hip Hop Pendant │ │
│ Shivas │ │ $8,000 · Rose Gold · Natural VVS │ │
│ │ │ Received 14 min ago · ⚠ Karat unconfirmed │ │
│ ───── │ │ [View] [Route Now →] │ │
│ │ └───────────────────────────────────────────────────────────┘ │
│ QUEUES │ ┌───────────────────────────────────────────────────────────┐ │
│ CAD HipHop│ │ [img] CJ-2026-001233 · Prime · Bridal Ring │ │
│ CAD Bridal│ │ $3,200 · 14kt Rose Gold │ │
│ Coral │ │ Received 31 min ago · Brief complete ✓ │ │
│ │ │ [View] [Route Now →] │ │
│ │ └───────────────────────────────────────────────────────────┘ │
│ │ │
│ │ ⏳ PENDING / IN PROGRESS │
│ │ ┌───────────────────────────────────────────────────────────┐ │
│ │ │ CJ-2026-001230 · Icechamp · Cuban Chain · 2h ago │ │
│ │ │ → Routed to CAD HipHop · In Design · 18h left │ │
│ │ └───────────────────────────────────────────────────────────┘ │
└────────────┴─────────────────────────────────────────────────────────────────┘Screen D2 — Job Detail Panel (split view)
┌──────────────────────────────────────────────────────────────────────────────┐
│ CHANDRA OS MY QUEUE 🔔 3 [RP] Rupsa │
├────────────┬──────────────────────────────┬──────────────────────────────── │
│ │ │ │
│ ◉ My Queue│ 🆕 CJ-2026-001234 ←selected│ CJ-2026-001234 │
│ │ 🆕 CJ-2026-001233 │ Icechamp · Received 14m ago │
│ │ ⏳ CJ-2026-001230 │ SLA: Route within 1h 46m ⚠ │
│ │ │ ────────────────────────── │
│ │ │ │
│ │ │ ORIGINAL MESSAGE │
│ │ │ ┌────────────────────────────┐ │
│ │ │ │ "Hi, need a pendant. Big │ │
│ │ │ │ bussdown, rose gold, │ │
│ │ │ │ around $8k. See ref." │ │
│ │ │ │ [img_001.jpg] │ │
│ │ │ └────────────────────────────┘ │
│ │ │ │
│ │ │ AI BRIEF [Edit ✎] │
│ │ │ Category Hip Hop Pendant │
│ │ │ Metal Rose Gold │
│ │ │ Karat ⚠ Not specified │
│ │ │ Budget $8,000 │
│ │ │ Stones Natural · Bussdown │
│ │ │ Deadline — │
│ │ │ │
│ │ │ Est. weight 12g – 16g │
│ │ │ Est. diamonds 3.2ct – 4.0ct │
│ │ │ │
│ │ │ CUSTOMER HISTORY [See all] │
│ │ │ Avg order: $9,200 │
│ │ │ Prefers 14kt in 8/10 orders │
│ │ │ Last order: CJ-2026-000891 │
│ │ │ │
│ │ │ ┌──────────────────────────┐ │
│ │ │ │ [Route to Design →] │ │
│ │ │ └──────────────────────────┘ │
└────────────┴──────────────────────────────┴──────────────────────────────── │Desktop notes:
- Left sidebar: navigation + customer/queue filters
- Middle panel: job list (scrollable)
- Right panel: job detail (slides in on click)
- "Route to Design →" CTA opens COS-RTE-001 routing modal
Out of Scope
| Item | Handled in |
|---|---|
| RM routing the job to design team | COS-RTE-001 |
| Email-based intake | COS-INQ-002 |
| Pricing calculation | COS-PRC-001 |
| Outbound WhatsApp for approvals | COS-APR-001 |
| Gati integration | COS-INT-001 |