Bạn đang vận hành website bảo hiểm và cần một form thu lead thống nhất cho tất cả sản phẩm — Du lịch, Xe, Sức khỏe, Nhà — mà không muốn cài chục plugin khác nhau? BảoHiểmVui One‑Form Lead chính là giải pháp đó: một shortcode duy nhất, một bảng database dùng chung, thông báo Telegram tức thì và giao diện quản lý lead ngay trong WordPress Admin.

---

1. Tổng quan — Plugin làm được gì?

Plugin hoạt động theo mô hình “1 cửa”: dù khách ghé trang bảo hiểm xe hay trang du lịch, họ đều submit vào cùng một endpoint, lead lưu vào cùng một bảng wp_bhv_leads. Đội sales không cần kiểm tra nhiều nơi.

🧩 Tính năng	⚙️ Kỹ thuật	📊 Quản lý
Form 4 sản phẩm trong 1 shortcode Panel mở rộng theo từng sản phẩm Chế độ lite (rút gọn) & full	Bootstrap 5.3 + Alpine.js 3 Không conflict khi đã có sẵn Anti-spam 10 giây / IP	Bảng lead tập trung Lọc, tìm kiếm, phân trang Xuất CSV & Telegram notify

---

2. Yêu cầu hệ thống

Thành phần	Phiên bản tối thiểu	Ghi chú
WordPress	5.8+	Khuyến nghị 6.x
PHP	7.4+	Khuyến nghị 8.1+
MySQL / MariaDB	5.7+ / 10.3+	Cần hỗ trợ LONGTEXT
Internet server	Bắt buộc	Để gọi CDN Bootstrap/Alpine & Telegram API
Quyền Admin WP	manage_options	Để xem và quản lý lead

---

3. Cài đặt Plugin (chỉ 3 bước)

Bước 1 — Upload file plugin

Giải nén file .zip và upload thư mục bhv-oneform-lead/ vào /wp-content/plugins/. Cấu trúc thư mục đúng chuẩn:

wp-content/plugins/
  bhv-oneform-lead/
    bhv-oneform-lead.php          ← File chính (khai báo plugin header)
    includes/
      class-bhv-model.php         ← Model + DB install + Telegram
      class-bhv-admin.php         ← Giao diện quản trị Admin
      shortcode-form-alpine.php   ← Render shortcode front-end

Bước 2 — Kích hoạt

1. Vào WordPress Admin → Plugins → Installed Plugins.
2. Tìm “BảoHiểmVui – One‑Form Lead” → nhấn Activate.
3. Plugin tự động tạo bảng wp_bhv_leads trong database (hook activation).

Bước 3 — Xác nhận bảng DB

Mở phpMyAdmin, tìm bảng {prefix}bhv_leads. Nếu thấy bảng với 19 cột → cài đặt thành công. Giờ bạn có thể chuyển sang cấu hình Telegram.

---

4. Cấu hình Telegram — Nhận thông báo lead tức thì

Đây là tính năng được yêu thích nhất: mỗi khi khách submit form, Telegram của bạn nhận ngay tin nhắn với tên, SĐT, sản phẩm quan tâm. Không cần F5 admin.

4.1 Tạo Telegram Bot

1. Mở Telegram, tìm kiếm @BotFather và nhắn /newbot.
2. Đặt tên bot: ví dụ BaoHiemVui Lead Bot.
3. BotFather trả về Bot Token — lưu lại ngay!

Ví dụ Bot Token: 7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

4.2 Lấy Chat ID

1. Mở chat với bot vừa tạo, gửi tin nhắn bất kỳ (ví dụ: “hello”).
2. Truy cập URL sau trên trình duyệt (thay TOKEN bằng token của bạn):

https://api.telegram.org/bot{TOKEN}/getUpdates

3. Trong JSON trả về, tìm "chat" → "id" → đó là Chat ID.

{
  "result": [{
    "message": {
      "chat": { "id": -1001234567890, "type": "supergroup" }
    }
  }]
}
→ Chat ID = -1001234567890  (số âm = group/channel)

4.3 Nhập vào Plugin

1. Vào WP Admin → BảoHiểmVui → Cài đặt.
2. Điền Telegram Bot Token.
3. Điền Telegram Chat ID.
4. Nhấn Lưu cài đặt → test bằng cách submit thử 1 lead.

---

5. Sử dụng Shortcode

Nhận tư vấn bảo hiểm nhanh

Điền thông tin → chuyên viên liên hệ (miễn phí)

Zalo: 0938 555 693 Gọi: 0938 555 693

Shortcode có thể nhúng vào trang, bài viết, widget Shortcode, hoặc gọi từ PHP template. Dưới đây là toàn bộ tham số và ví dụ thực tế.

5.1 Bảng tham số

Tham số	Mặc định	Giá trị hợp lệ	Mô tả
type	full	full | lite	full: form đầy đủ + panel mở rộng. lite: chỉ 4 trường cơ bản
product	(trống)	travel | auto | health | home	Preset sẵn tab sản phẩm khi trang tải
source	tự động	chuỗi bất kỳ	Override giá trị source lưu vào DB. Tốt cho tracking
enable_bootstrap	1	1 | 0	Tắt nếu theme đã load Bootstrap 5 để tránh duplicate
enable_alpine	1	1 | 0	Tắt nếu site đã load Alpine.js ở nơi khác

5.2 Ví dụ thực tế

▶ Form đầy đủ — dùng ngay không cần tham số

            
            
                        
            

  

    

      

        

          
Nhận tư vấn bảo hiểm nhanh
          
Điền thông tin → chuyên viên liên hệ (miễn phí)
        
        

          Zalo: 0938 555 693
          Gọi: 0938 555 693
        
      

      


      

        
                
        
        
        
        
        

        
        

        
        
      

      
    
  

▶ Form lite — dùng cho popup hay sidebar nhỏ

            
            
                        
            

  

    

      

        

          
Nhận tư vấn bảo hiểm nhanh
          
Điền thông tin → chuyên viên liên hệ (miễn phí)
        
        

          Zalo: 0938 555 693
          Gọi: 0938 555 693
        
      

      


      

        
                
        
        
        
        
        

        
        

        
        
      

      
    
  

▶ Landing page bảo hiểm xe — preset sẵn tab Xe

            
            
                        
            

  

    

      

        

          
Nhận tư vấn bảo hiểm nhanh
          
Điền thông tin → chuyên viên liên hệ (miễn phí)
        
        

          Zalo: 0938 555 693
          Gọi: 0938 555 693
        
      

      


      

        
                
        
        
        
        
        

        
        

        
        
      

      
    
  

▶ Landing page du lịch Q2 — có tracking source

            
            
                        
            

  

    

      

        

          
Nhận tư vấn bảo hiểm nhanh
          
Điền thông tin → chuyên viên liên hệ (miễn phí)
        
        

          Zalo: 0938 555 693
          Gọi: 0938 555 693
        
      

      


      

        
                
        
        
        
        
        

        
        

        
        
      

      
    
  

▶ Theme đã có Bootstrap — không load lại

            
            

  

    

      

        

          
Nhận tư vấn bảo hiểm nhanh
          
Điền thông tin → chuyên viên liên hệ (miễn phí)
        
        

          Zalo: 0938 555 693
          Gọi: 0938 555 693
        
      

      


      

        
                
        
        
        
        
        

        
        

        
        
      

      
    
  

▶ Gọi từ PHP template (page.php, functions.php…)

<?php echo do_shortcode('            
            
                        
            

  

    

      

        

          
Nhận tư vấn bảo hiểm nhanh
          
Điền thông tin → chuyên viên liên hệ (miễn phí)
        
        

          Zalo: 0938 555 693
          Gọi: 0938 555 693
        
      

      


      

        
                
        
        
        
        
        

        
        

        
        
      

      
    
  



'); ?>

---

6. Quản lý Lead trong WordPress Admin

Sau khi có lead, toàn bộ quy trình xử lý diễn ra ngay trong WP Admin → BảoHiểmVui. Không cần phần mềm CRM ngoài cho quy mô vừa và nhỏ.

6.1 Màn hình danh sách Lead

Bảng lead hiển thị đầy đủ thông tin với 3 bộ lọc:

• Lọc theo sản phẩm: Du lịch / Xe / Sức khỏe / Nhà / Khác
• Lọc theo trạng thái: Mới / Đã liên hệ / Chốt / Trượt
• Tìm kiếm tự do: theo tên, SĐT, email

Nhấn “Xem” ở cột chi tiết để xem fields_json (dữ liệu sản phẩm mở rộng), URL trang, Referrer, UTM tracking và trạng thái đồng bộ Mautic.

6.2 Trạng thái lead & phân công

Giá trị DB	Nhãn hiển thị	Ý nghĩa & khi nào dùng
new	🆕 Mới	Lead vừa vào, chưa ai xử lý
contacted	📞 Đã liên hệ	Đã gọi điện hoặc nhắn Zalo cho khách
closed_won	🏆 Chốt	Khách đã mua bảo hiểm thành công
closed_lost	❌ Trượt	Khách không mua hoặc không liên lạc được

Sau khi chọn trạng thái, điền tên người phụ trách (trường Assigned To) rồi nhấn Lưu. Trang tự reload, thay đổi ghi ngay vào DB.

6.3 Xuất CSV để phân tích

1. Vào WP Admin → BảoHiểmVui.
2. Nhấn nút Xuất CSV ở góc trên bên phải.
3. File tải về dạng: bhv_leads_20260401_215400.csv

File CSV bao gồm toàn bộ 19 cột: từ id, created_at đến các UTM param và pushed_to_mautic_at. Dùng ngay với Google Sheets hoặc Excel để báo cáo.

---

7. API nội bộ — Tích hợp từ Plugin khác

Đây là điểm mạnh về kiến trúc: plugin TNDS, Du lịch, hay bất kỳ plugin nào khác của bạn đều có thể đẩy lead vào cùng bảng chung qua 2 cơ chế.

7.1 Hàm bhv_leads_insert()

Gọi từ bất kỳ đâu trong WordPress (plugin, theme, functions.php):

$id = bhv_leads_insert([
    // === Bắt buộc ===
    'product'   => 'auto',            // travel | auto | health | home | other
    'full_name' => 'Nguyễn Văn A',
    'phone'     => '0938555693',

    // === Tuỳ chọn ===
    'email'     => 'a@gmail.com',
    'source'    => 'plugin_tnds_v2',
    'note'      => 'Ghi chú nội bộ',

    // Dữ liệu mở rộng theo sản phẩm (lưu dạng JSON)
    'fields'    => [
        'auto_model'  => 'Toyota Vios 2021',
        'auto_type'   => 'combo',
        'auto_value'  => '650000000',
    ],

    // Tracking
    'page_url'     => 'https://baohiemvui.vn/bao-hiem-xe',
    'utm_source'   => 'google',
    'utm_medium'   => 'cpc',
    'utm_campaign' => 'xe_q2_2026',
]);
// $id = insert_id của lead vừa tạo

7.2 Action Hook bhv_lead_inserted

Hook bắn ra ngay sau khi insert thành công — dùng để gọi CRM, email automation, Mautic:

add_action('bhv_lead_inserted', function($lead_id, $args) {
    // $lead_id : ID vừa insert
    // $args    : mảng dữ liệu gốc

    // Ví dụ: đồng bộ sang Mautic
    my_mautic_push_contact(
        $args['phone'],
        $args['email'],
        $args['full_name'],
        $args['product']
    );
}, 10, 2);

---

8. Cấu trúc Database — Bảng wp_bhv_leads

Cột	Kiểu dữ liệu	Mô tả
id	BIGINT UNSIGNED	Khóa chính, tự tăng
created_at	DATETIME	Thời điểm tạo lead
product	VARCHAR(32)	travel | auto | health | home | other
source	VARCHAR(64)	Nguồn form (form_one_full, plugin_tnds…)
status	VARCHAR(32)	new | contacted | closed_won | closed_lost
assigned_to	VARCHAR(190)	Tên người phụ trách
full_name	VARCHAR(190)	Họ tên khách hàng
phone	VARCHAR(64)	SĐT / Zalo
email	VARCHAR(190)	Email (nullable)
note	TEXT	Ghi chú của khách
fields_json	LONGTEXT	Dữ liệu mở rộng theo sản phẩm (JSON)
page_url	TEXT	URL trang khách submit
referrer	TEXT	document.referrer
utm_source/medium/campaign/term/content	VARCHAR(190)	UTM tracking params (5 cột riêng)
pushed_to_mautic_at	DATETIME	Null nếu chưa đồng bộ Mautic

Index tự động tạo: idx_created, idx_product, idx_status — đảm bảo query nhanh khi bảng có hàng nghìn lead.

---

9. Troubleshooting — Xử lý sự cố thường gặp

🔧 Form không hiển thị / màn hình trắng

Kiểm tra plugin đã được Activate. Bật WP_DEBUG=true trong wp-config.php để xem lỗi PHP chi tiết. Kiểm tra lại cú pháp shortcode.

🎨 Form hiển thị nhưng không có style

Nguyên nhân: enable_bootstrap="0" nhưng theme không load Bootstrap. Thêm lại enable_bootstrap="1" hoặc load Bootstrap từ theme. Kiểm tra CSP header có block cdn.jsdelivr.net không.

📭 Submit xong nhưng không thấy lead trong Admin

Kiểm tra bảng wp_bhv_leads tồn tại trong phpMyAdmin. Tạm tắt plugin Security/Firewall để test (có thể chặn admin-post.php). Xem wp-content/debug.log tìm lỗi SQL.

📱 Telegram không nhận thông báo

Xác nhận Bot Token & Chat ID đúng trong Admin → Cài đặt. Bot phải được mời vào group và có quyền gửi tin. Xem debug.log tìm dòng [BHV] Telegram để đọc HTTP error code.

🚫 Lỗi “Nonce không hợp lệ” khi submit

Xảy ra khi session hết hạn (>12 giờ) hoặc plugin cache HTML quá mạnh. Cấu hình cache loại trừ trang chứa form, hoặc disable cache cho logged-in users.

🔁 Cảnh báo bảng đã tồn tại khi Activate

Đây là thông báo bình thường từ dbDelta — không phải lỗi. Plugin dùng dbDelta nên an toàn khi activate nhiều lần, chỉ update schema nếu cần.

---

10. Changelog

Phiên bản	Ngày	Thay đổi chính
1.1.0	04/2026	Guard double-load Bootstrap/Alpine. Cải tiến Telegram notify (log lỗi chi tiết). Thêm Export CSV. Admin pagination. Anti-spam transient.
1.0.0	03/2026	Phiên bản đầu tiên: form 4 sản phẩm, bảng DB chung wp_bhv_leads, bhv_leads_insert() API, admin quản lý lead cơ bản.

---