Workflow: WhatsApp → Lead / Suport

Module implicate: WhatsApp (Inbox · Bots · Campaigns · Templates) · WhatsApp API (Notificări Events) · Leads · Tickets · Marketing Automation
Cine îl folosește: Sales · Customer Support · Marketing
Durata tipică: Real-time (mesaje incoming) + ciclu campanie (onetime/recurring)

Overview

CRMConnect are trei module WhatsApp distincte cu scopuri complet diferite:

Acest workflow acoperă modulul principal whatsapp (inbox + auto-lead + boti + campanii) și whatsapp_api (notificări events).

Atenție: Crearea automată de tichete din conversații WhatsApp este parțial implementată (AI colectează datele dar insert-ul în tbltickets lipsește din cod). Tichetele se creează manual de către staff din interfața de chat.

Diagrama fluxului

[SETUP — admin, o singură dată]
  │
  ├── Meta App + WhatsApp Business Account configurat
  ├── Webhook înregistrat la Meta: {site_url}/whatsapp/webhook/getdata
  ├── Număr de telefon conectat în WhatsApp → Numbers
  ├── Templates încărcate din Meta (sync manual sau cron orar)
  └── Auto-lead activat (opțional): whatsapp_auto_lead_settings = 'enable'
  │
  ↓
[MESAJ INCOMING]
  │
  ├── Meta trimite webhook POST la /whatsapp/webhook/getdata
  ├── Sistem caută numărul în: leads → contacts → staff
  │
  ├── NUMĂR IDENTIFICAT → mapează conversația la înregistrarea existentă
  │     rel_type = 'leads' / 'contacts' / 'staff'
  │
  └── NUMĂR NECUNOSCUT:
        ├── auto_lead ACTIVAT → crează Lead automat
        │     status = whatsapp_lead_status
        │     source = whatsapp_lead_source
        │     assigned = whatsapp_lead_assigned
        │     rel_type = 'leads'
        │
        └── auto_lead DEZACTIVAT (implicit) → rel_type = 'general'
              staff vede conversația ca necunoscută în inbox
  │
  ↓
[BOT (dacă activ)]
  │
  ├── BotHandler::processBots() evaluează TOATE bot-urile active
  ├── Trigger match → trimite răspuns automat (text / template / meniu / AI)
  └── Fără match → mesajul rămâne în inbox pentru răspuns manual
  │
  ↓
[RĂSPUNS STAFF / ESCALADARE]
  │
  ├── Staff deschide /admin/whatsapp → inbox
  ├── Vede conversațiile grupate: identified (lead/contact) + general
  ├── Răspunde direct sau folosește Quick Replies
  └── Creează manual Tichet din conversație (dacă suportul o cere)
  │
  ↓
[CAMPANIE BULK (flux separat)]
  │
  ├── Creat template Meta aprobat
  ├── Campanie nouă: tip (onetime/recurring/custom), destinatari, număr expeditor
  ├── send_now=1 sau scheduled_send_time planificat
  └── Cron execută trimiterea → status per destinatar: failed(0) / success(2) / invalid(3)
  │
  ↓
[NOTIFICĂRI EVENTS — modul whatsapp_api]
  │
  ├── Lead creat → template mapat pe categoria 'leads' trimis automat
  ├── Tichet creat → template mapat pe 'ticket' trimis automat
  ├── Factură adăugată → template mapat pe 'invoice'
  └── Plată înregistrată → template mapat pe after_payment_added

[CONVERSAȚIE ÎNCHISĂ / LEAD CALIFICAT ✓]

Pas cu pas

1. Setup Meta + conexiune (admin)

Unde: /admin/whatsapp → Settings → Connection tab

Condiție: Toate câmpurile de mai jos sunt is_admin() only — staff obișnuit nu poate accesa.

URL webhook de înregistrat la Meta:

{site_url}/whatsapp/webhook/getdata

Subscripții necesare la Meta: messages + message_status_updates.

Numerele de telefon: după conectarea credențialelor, numerele se adaugă în WhatsApp → Numbers (via OAuth sau manual). Setați un număr ca default pentru trimiteri.

Templates: WhatsApp → Templates → Load Templates (sincronizează din Meta). Cron-ul reîmprospătează automat la fiecare oră.

2. Configurare auto-lead (opțional)

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

Flux de identificare număr (în ordine):

1. Caută în tblleads.phonenumber (normalizat fără caractere non-numerice)
2. Caută în tblcontacts.phonenumber
3. Caută în tblstaff.phonenumber
4. Dacă niciun match → crează lead (dacă auto_lead enabled) sau lasă ca general

3. Configurare boti (opțional)

Unde: /admin/whatsapp → Bots → New Bot

Tipuri de trigger (reply_type):

Tipuri de răspuns (bot_type):

Configurare AI (pentru bot_type=12): Unde: Settings → AI tab: alegeți provider (openai/gemini), introduceți API key, setați whatsapp_openai_status:

• auto = AI răspunde automat la toate mesajele fără match pe alți boti
• manual = AI generează sugestie de răspuns vizibilă staff-ului, dar nu trimite automat

4. Inbox și răspuns manual

Unde: /admin/whatsapp (necesită permisiunea whatsapp_chat → view)

Conversațiile sunt grupate după rel_type:

• leads — conversații legate de lead-uri
• contacts — conversații legate de contacte
• staff — conversații cu angajați
• general — numere neidentificate (auto_lead dezactivat)

Staff poate:

• Răspunde cu text, fișiere, Quick Replies (tblquick_replies)
• Asigna conversația altui staff
• Crea manual un Tichet din interfață (tichetul NU se crează automat)
• Vedea istoricul complet al mesajelor (tblwhatsapp_interaction_messages)

5. Campanii bulk

Unde: /admin/whatsapp → Campaigns → New Campaign

Condiții prealabile:

• Template Meta aprobat (status = 'APPROVED' în tblwhatsapp_interaction_templates)
• Cel puțin un număr de telefon configurat

Câmpuri campanie:

Statusuri per destinatar (tblwhatsapp_campaign_data):

Statusuri livrare (message_status): sent → delivered → read

Atenție: Campaniile sunt executate de cron, nu instant. Dacă cron-ul CRM nu rulează, campaniile planificate nu se trimit.

6. Notificări automate la events CRM (modul whatsapp_api)

Unde: /admin/whatsapp_api → Template Mapping

Modulul whatsapp_api se declanșează independent de inbox, pe baza hook-urilor:

Configurare per notificare:

1. Sync templates: WhatsApp API → Templates → Load
2. Creare mapping: WhatsApp API → Template Mapping → Add
3. Alegeți template + category + send_to (contact / lead / staff) + parametrii header/body/footer

Modulul whatsapp_api împarte credențialele Meta cu modulul whatsapp (același access_token și phone_number_id), dar le stochează separat în propriile opțiuni.

Permisiuni necesare

Gotchas

Referințe module

• WhatsApp — documentație modul principal
• Leads — lead-uri create automat
• Tickets — creare manuală tichete
• Marketing Campaigns — campanii email (separate de WA)