Chatbot Telegram development

🔹 FLOW BOT (berdasarkan code kau)

1. Update masuk dari Telegram

• Bot terima JSON dari php://input.

• Extract:

  • chat_id

  • firstname

  • text

  • (juga handle kalau update datang dari callback_query).

---

2. Handle Special Case

• User baru join group

  • Bot hantar mesej welcome dalam group.

  • Bot juga cuba hantar DM private welcome.

• Lead Capture Check

  • Panggil handleLeadCapture() (daripada lead-capture.php).

  • Kalau match keyword dari Sheet tab Redirect, terus masuk flow lead capture.

---

3. Session Handler

• Session user disimpan dalam sessions.json.

• Ada check:

  • active / not active

  • last_activity

  • mode → exact atau contains

  • Timeout → 5 minit (kalau lebih, sesi auto tamat).

---

4. Commands

• /start

  • Kalau ada param → terus treat param tu sebagai keyword.

  • Kalau tiada param → bagi menu default (butang "Cek Kekosongan").

• /end

  • Tamatkan sesi user.

• /stat

  • Hantar statistik: total chat, private, group.

• /notifythem (admin only)

  • Masuk mode broadcast → mesej seterusnya akan dihantar kepada semua user.

• /endgroupall

  • Clear semua sesi group dari sessions.json.

---

5. Greeting / Activate

• Kalau user taip keyword tertentu:

  • mula, husna, /husna → mode exact (jawapan direct ikut keyword penuh).

  • hai, salam, hello, carian, /carian → mode contains (lebih fleksibel, keyword mengandungi perkataan).

---

6. Search Flow (processSearch)

1. Ambil data dari Google Sheet (tab default Sheet1).

2. Normalise keywords.

3. Bandingkan dengan input user:

   • Kalau match → kumpul semua row.

   • Kalau tak match → reply fallback “tak ada jawapan, sila ke menu/live admin”.

4. Kalau match:

   • Gantikan {firstname} dalam mesej reply.

   • Kalau row ada gambar (col 5) → hantar photo message.

   • Kalau ada butang (col 3 & 4) → buat inline keyboard.

   • Kalau banyak result → tambah butang Ke Menu.

---

7. Lead Capture Flow (handleLeadCapture)

• Step 0: Keyword trigger → bot tanya nak confirm → user perlu /start.

• Step 1: Bot minta nama.

• Step 2: Bot minta nombor WhatsApp → validate format.

• Step 3:

  • Simpan ke Google Sheet tab Leads (nama, phone, prefix).

  • Hantar mesej “thank you” custom dari sheet Redirect.

  • Notify admin dengan mesej + link wasap follow-up.

  • Reset sesi lead capture.

---

8. Callback Query Handling

• Kalau callback dari group:

  • Kalau bukan admin → suruh user buka DM.

  • Tukar channel ke private DM.

  • Pastikan session aktif.

• Kalau callback dalam DM:

  • Cuba handle lead capture dulu.

  • Kalau bukan → fallback ke search.

---

9. Admin Features

• Hanya user ID dalam array isAdmin() yang dapat akses:

  • /notifythem (broadcast ke semua user).

  • /endgroupall.

---

🔹 Ringkas (High-Level Journey)

1. User masuk / start → Bot greet / bagi menu.

2. User tanya keyword → Bot cari dalam Sheet → reply + button/gambar.

3. Kalau trigger lead → Masuk flow capture data (nama, phone).

4. Data lead → Save ke Sheet → Notify admin.

5. Admin boleh broadcast / clear session bila perlu.

6. Sesi auto tamat kalau idle > 5 minit.