Workflow: WhatsApp → Lead / Support

Modules involved: WhatsApp (Inbox · Bots · Campaigns · Templates) · WhatsApp API (Event Notifications) · Leads · Tickets · Marketing Automation
Who uses it: Sales · Customer Support · Marketing
Typical duration: Real-time (incoming messages) + campaign cycle (onetime/recurring)

Overview

CRMConnect has three distinct WhatsApp modules with completely different purposes:

This workflow covers the main whatsapp module (inbox + auto-lead + bots + campaigns) and whatsapp_api (event notifications).

Note: Automatic ticket creation from WhatsApp conversations is partially implemented (AI collects data but the insert into tbltickets is missing from code). Tickets are created manually by staff from the chat interface.

Flow diagram

[SETUP — admin, once only]
  │
  ├── Meta App + WhatsApp Business Account configured
  ├── Webhook registered with Meta: {site_url}/whatsapp/webhook/getdata
  ├── Phone number connected in WhatsApp → Numbers
  ├── Templates loaded from Meta (manual sync or hourly cron)
  └── Auto-lead enabled (optional): whatsapp_auto_lead_settings = 'enable'
  │
  ↓
[INCOMING MESSAGE]
  │
  ├── Meta sends webhook POST to /whatsapp/webhook/getdata
  ├── System searches number in: leads → contacts → staff
  │
  ├── NUMBER IDENTIFIED → maps conversation to existing record
  │     rel_type = 'leads' / 'contacts' / 'staff'
  │
  └── UNKNOWN NUMBER:
        ├── auto_lead ENABLED → creates Lead automatically
        │     status = whatsapp_lead_status
        │     source = whatsapp_lead_source
        │     assigned = whatsapp_lead_assigned
        │     rel_type = 'leads'
        │
        └── auto_lead DISABLED (default) → rel_type = 'general'
              staff sees conversation as unknown in inbox
  │
  ↓
[BOT (if active)]
  │
  ├── BotHandler::processBots() evaluates ALL active bots
  ├── Trigger match → sends automatic response (text / template / menu / AI)
  └── No match → message remains in inbox for manual response
  │
  ↓
[STAFF RESPONSE / ESCALATION]
  │
  ├── Staff opens /admin/whatsapp → inbox
  ├── Sees conversations grouped: identified (lead/contact) + general
  ├── Replies directly or uses Quick Replies
  └── Creates ticket manually from conversation (if support requires it)
  │
  ↓
[BULK CAMPAIGN (separate flow)]
  │
  ├── Approved Meta template created
  ├── New campaign: type (onetime/recurring/custom), recipients, sender number
  ├── send_now=1 or scheduled_send_time planned
  └── Cron executes sending → status per recipient: failed(0) / success(2) / invalid(3)
  │
  ↓
[EVENT NOTIFICATIONS — whatsapp_api module]
  │
  ├── Lead created → template mapped to 'leads' category sent automatically
  ├── Ticket created → template mapped to 'ticket' sent automatically
  ├── Invoice added → template mapped to 'invoice'
  └── Payment recorded → template mapped to after_payment_added

[CONVERSATION CLOSED / LEAD QUALIFIED ✓]

Step by step

1. Meta setup + connection (admin)

Where: /admin/whatsapp → Settings → Connection tab

Condition: All fields below are is_admin() only — regular staff cannot access.

Webhook URL to register with Meta:

{site_url}/whatsapp/webhook/getdata

Required Meta subscriptions: messages + message_status_updates.

Phone numbers: after connecting credentials, numbers are added in WhatsApp → Numbers (via OAuth or manually). Set one number as default for outgoing messages.

Templates: WhatsApp → Templates → Load Templates (syncs from Meta). Cron automatically refreshes every hour.

2. Auto-lead configuration (optional)

Where: /admin/whatsapp → Settings → Auto Lead tab

Number identification flow (in order):

1. Search in tblleads.phonenumber (normalized without non-numeric characters)
2. Search in tblcontacts.phonenumber
3. Search in tblstaff.phonenumber
4. If no match → create lead (if auto_lead enabled) or leave as general

3. Bot configuration (optional)

Where: /admin/whatsapp → Bots → New Bot

Trigger types (reply_type):

Response types (bot_type):

AI configuration (for bot_type=12): Where: Settings → AI tab: choose provider (openai/gemini), enter API key, set whatsapp_openai_status:

• auto = AI automatically responds to all messages with no match on other bots
• manual = AI generates a response suggestion visible to staff, but does not send automatically

4. Inbox and manual response

Where: /admin/whatsapp (requires whatsapp_chat → view permission)

Conversations are grouped by rel_type:

• leads — conversations linked to leads
• contacts — conversations linked to contacts
• staff — conversations with employees
• general — unidentified numbers (auto_lead disabled)

Staff can:

• Reply with text, files, Quick Replies (tblquick_replies)
• Assign conversation to another staff member
• Manually create a Ticket from the interface (ticket is NOT created automatically)
• View complete message history (tblwhatsapp_interaction_messages)

5. Bulk campaigns

Where: /admin/whatsapp → Campaigns → New Campaign

Prerequisites:

• Approved Meta template (status = 'APPROVED' in tblwhatsapp_interaction_templates)
• At least one phone number configured

Campaign fields:

Statuses per recipient (tblwhatsapp_campaign_data):

Delivery statuses (message_status): sent → delivered → read

Note: Campaigns are executed by cron, not instantly. If the CRM cron is not running, scheduled campaigns are not sent.

6. Automatic notifications on CRM events (whatsapp_api module)

Where: /admin/whatsapp_api → Template Mapping

The whatsapp_api module fires independently of the inbox, based on hooks:

Configuration per notification:

1. Sync templates: WhatsApp API → Templates → Load
2. Create mapping: WhatsApp API → Template Mapping → Add
3. Choose template + category + send_to (contact / lead / staff) + header/body/footer parameters

The whatsapp_api module shares Meta credentials with the whatsapp module (same access_token and phone_number_id), but stores them separately in its own options.

Required permissions

Gotchas

Module references

• WhatsApp — main module documentation
• Leads — automatically created leads
• Tickets — manual ticket creation
• Marketing Campaigns — email campaigns (separate from WA)