Chuyển tới nội dung chính

7i. Cầu Telegram (Zalo ↔ Telegram) — Hướng dẫn cấu hình

Mục đích: sale đọc & trả lời chat khách Zalo ngay trong Telegram. Mỗi nick Zalo có 1 group Telegram riêng, mỗi khách = 1 topic. Tin chạy 2 chiều tự động. Quyền: Quản trị viên (admin/owner) — riêng phần điền cấu hình server cần người quản trị server. Số liệu/ảnh là dữ liệu demo.

Cầu Telegram cần chuẩn bị bên ngoài CRM (tạo bot + lấy khoá Telegram), sau đó bật cầu cho từng nick ngay trong CRM.

🧩 Có 2 "tài khoản Telegram" khác nhau:

  • Bot (vd @hs_crm_bridge_bot) — đăng tin vào group + nhận tin sale gõ.
  • Tài khoản công ty (provisioner) — dùng để tạo group (bot không tự tạo group được).

Phần 1 — Chuẩn bị bên ngoài CRM​

A. Tạo Bot Telegram (qua @BotFather)​

  1. Mở Telegram, tìm @BotFather → gửi /newbot.
  2. Đặt tên hiển thị và username (username phải kết thúc bằng bot, vd hs_crm_bridge_bot).
  3. BotFather trả về Bot Token dạng 8637568596:AAH... → ghi lại.
  4. Ghi lại luôn username bot (bỏ dấu @).

B. Lấy API ID & API Hash (my.telegram.org)​

Bước này lấy 2 khoá cho tài khoản Telegram công ty sẽ tạo group.

B1. Vào my.telegram.org, nhập số điện thoại tài khoản công ty (định dạng quốc tế, vd +84...) ➊ → bấm Next ➋. Telegram gửi mã xác nhận vào app Telegram của số đó — nhập mã để đăng nhập.

Đăng nhập my.telegram.org bằng số điện thoại

B2. Vào màn hình "Your Telegram Core" → bấm API development tools ➊.

Chọn API development tools

B3. Điền App title và Short name (tuỳ ý, vd zcrmbridge) → tạo app. Sau đó copy lại:

  • App api_id ➊ (dãy số)
  • App api_hash ➋ (chuỗi)

Lấy api_id và api_hash

🔒 api_hash là bí mật — đừng chia sẻ công khai.

C. Sinh "session" cho tài khoản công ty (cần người quản trị server)​

Để CRM thay mặt tài khoản công ty tạo group, cần tạo chuỗi session một lần bằng script trên server — luồng đăng nhập 2 bước (nhập OTP, và mật khẩu 2 lớp nếu có). Việc này do quản trị server thực hiện theo tài liệu kỹ thuật: ➡️ HUONG-DAN-CAU-HINH-TELEGRAM-BRIDGE.md — Mục 4

Phần 2 — Khai báo cấu hình (server) & khởi động​

Quản trị server điền các giá trị Phần 1 vào file .env rồi khởi động lại:

TELEGRAM_BRIDGE_BOT_TOKEN=<token bot — A>
TELEGRAM_BRIDGE_BOT_USERNAME=<username bot, không @ — A>
TELEGRAM_PROVISIONER_API_ID=<api_id — B3>
TELEGRAM_PROVISIONER_API_HASH=<api_hash — B3>
TELEGRAM_PROVISIONER_SESSION=<session — C>

Sau khi khởi động, log server hiện [telegram-bridge] BẬT ... là thành công. Chi tiết: tài liệu kỹ thuật Mục 5.

Phần 3 — Bật cầu cho từng nick (trong CRM)​

  1. Vào trang quản lý nick Zalo (Tài khoản Zalo) → bấm vào 1 nick để mở bảng chi tiết bên phải.
  2. Kéo tới mục "Cầu Telegram":
    • Trạng thái: chấm 🟢 Đang bật / ⚪ Chưa bật (kèm mã group nếu đã bật).
    • Nút "Bật cầu Telegram" → hệ thống tự tạo group Telegram cho nick này + bật forum/topics + thêm bot làm quản trị. Xong, trạng thái chuyển sang Đang bật.

✅ Bạn KHÔNG cần tạo group, thêm bot, hay tạo topic thủ công — tất cả tự động. Topic cho mỗi khách tự sinh khi khách nhắn lần đầu.

  • Nút "Lấy mã liên kết (sale)" → hiện mã dạng /link XXXXX.

Mục Cầu Telegram trong chi tiết nick — trạng thái, bật cầu, lấy mã liên kết

Trong ảnh: ➊ trạng thái 🟢 Đang bật kèm mã group (vd group -100...7264); ➋ nút "Lấy mã liên kết (sale)"; ➌ mã /link ... vừa sinh (sale copy, dán cho bot — hết hạn sau 10 phút). Khi cầu đã bật, nút trên đổi thành "✓ Đã bật cầu" (không bấm lại được).

⚠️ Nút "Bật cầu Telegram" chỉ bấm được khi: đã cấu hình bot + tài khoản công ty (Phần 1–2), và bạn có quyền settings:edit. Nếu bị khóa, dòng chữ ngay dưới nút sẽ ghi rõ thiếu gì.

Thêm sale vào group (làm tay — 1 lần mỗi nick)​

Khi bật cầu, group chỉ có tài khoản công ty + bot. Sale muốn đọc/trả lời phải là thành viên group:

  1. Đăng nhập Telegram bằng tài khoản công ty (số đã dùng ở Phần 1B).
  2. Mở group 📱 ... — Cầu → Manage group → Invite Links → Create link (hoặc Add members).
  3. Gửi link mời cho các sale phụ trách nick đó → họ bấm vào để tham gia.

Liên kết tài khoản Telegram của sale​

Sau khi đã vào group, mỗi sale liên kết danh tính (để CRM gửi/nhận đúng người):

  1. Bấm "Lấy mã liên kết (sale)" → copy mã /link XXXXX (hết hạn 10 phút).
  2. Sale mở Telegram, chat với bot (vd @hs_crm_bridge_bot), gõ /link XXXXX ➊.
  3. Bot xác nhận: "✅ Đã liên kết tài khoản Telegram với CRM. Giờ bạn gửi tin được."

Sale gõ /link cho bot và bot xác nhận liên kết

Phần 4 — Dùng hằng ngày​

  • Khách nhắn Zalo → tin hiện trong topic của khách đó (trong group của nick), kèm nhãn người gửi + giờ.
  • Sale trả lời ngay trong topic Telegram → khách Zalo nhận (qua nick tương ứng).
  • Mỗi hội thoại khách = 1 topic riêng; ảnh/file từ Zalo được đẩy lên Telegram.

Group tự tạo với danh sách topic theo từng khách, chat ngay trong topic

Trong ảnh: cột trái là danh sách topic (mục General + mỗi khách 1 topic, tự sinh khi khách nhắn); bên phải là tin trong một topic — tin khách gắn nhãn 👤 {tên khách}, sale gõ thẳng trong topic để trả lời về Zalo.

💬 Hiện chiều Telegram → Zalo hỗ trợ văn bản. Gửi ảnh/file từ Telegram về Zalo sẽ bổ sung ở phiên bản sau.

Xử lý nhanh​

Vấn đềCách xử lý
Nút "Bật cầu" bị mờĐọc dòng chữ dưới nút: thiếu bot / thiếu tài khoản công ty / thiếu quyền settings:edit.
Không nhận mã ở my.telegram.orgMã gửi vào app Telegram của số đó (không phải SMS) — mở Telegram xem.
Sale gõ /link không nhậnMã hết hạn (10 phút) — lấy mã mới; đảm bảo gõ đúng bot của hệ thống.
Tin không qua đượcBáo quản trị server kiểm tra log telegram-bridge.

📎 Tài liệu kỹ thuật (devops): HUONG-DAN-CAU-HINH-TELEGRAM-BRIDGE.md