FBChat-Remake — Mã nguồn mở

Thư viện Python hiện đại cho Facebook Messenger API (không chính thức), hoạt động trên tài khoản người dùng

🇬🇧 English · 📦 PyPI · 📖 Tài liệu · 📊 Sơ đồ luồng · 🐛 Báo lỗi

📢 Thông báo quan trọng

Kể từ tháng 11/2024, Facebook đã chính thức triển khai mã hoá đầu cuối (End-to-End Encryption — E2EE) cho mọi cuộc trò chuyện giữa người dùng với người dùng trên Messenger.

Cập nhật 12/05/2026: fbchat-v2 đã chính thức hỗ trợ giải mã E2EE cho tin nhắn cá nhân Messenger thông qua module mới _messaging/_listening_e2ee.py + binary Go bridge-e2ee/. Schema sự kiện trả về giống hệt _listening.py cũ — chỉ cần đổi import là chạy.

Tin nhắn nhóm vẫn dùng _listening.py (MQTT WebSocket) như trước; tin nhắn 1–1 dùng _listening_e2ee.py.

⚠️ Tuyên bố miễn trừ — Đây không phải là sản phẩm chính thức của Facebook. Facebook đã có sẵn API chatbot chính thức tại đây. fbchat-v2 khác biệt ở chỗ nó xác thực bằng tài khoản / cookie người dùng Facebook thực, vốn tiềm ẩn rủi ro. Hãy cân nhắc kỹ trước khi sử dụng.

👋 Giới thiệu

Xin chào, mình là MinhHuyDev / raintee.dev — tác giả và người duy trì dự án này.

Trước hết, mình xin chân thành cảm ơn tất cả người dùng trong và ngoài nước đã đóng góp ý tưởng và báo lỗi cho dự án. Trong bản cập nhật lớn v2.x này, codebase đã được tái cấu trúc hoàn toàn, xử lý phần lớn các lỗi nhỏ tồn đọng và đặt nền móng cho những tính năng sắp tới như E2EE và async/await đầy đủ.

Tất nhiên vẫn sẽ còn những lỗi vặt khó tìm ra, hoặc các đoạn code chưa thật sự đồng bộ. Nếu bạn phát hiện ra vấn đề, hãy mở issue trên GitHub hoặc nhắn trực tiếp cho mình qua Telegram.

✨ Tính năng

fbchat-v2 đi theo một hướng hoàn toàn khác so với SDK chính thức: thay vì chỉ chạy trên một fanpage với access_token, thư viện điều khiển một tài khoản Facebook thật thông qua cookie hoặc thông tin đăng nhập, mở khoá toàn bộ bề mặt của Messenger.

Xác thực

🔐 Đăng nhập bằng username / password hoặc cookie phiên (*)
🍪 Tái sử dụng phiên đăng nhập — không cần đăng nhập lại mỗi lần chạy

Nhắn tin

📥 Đọc tin nhắn từ cả người dùng lẫn nhóm chat (thread)
🔐 E2EE listener cho tin nhắn cá nhân Messenger (Secret Conversations / Labyrinth) qua bridge Go
📤 Gửi văn bản, tệp đính kèm, nhãn dán (sticker), mention người dùng
🔍 Tìm kiếm tin nhắn và chuỗi hội thoại
✏️ Sửa tin nhắn đã gửi, thả cảm xúc, thu hồi tin, xử lý message requests
🎨 Đổi theme / nền thread Messenger và quản lý Messenger Notes 24h
📡 Listener real-time — phản hồi lệnh người dùng tức thì

Thread & Nhóm

👥 Tạo nhóm, thêm admin, đổi tên / emoji / biệt danh trong nhóm
📊 Tạo cuộc thăm dò ý kiến (poll) và lấy toàn bộ metadata của thread

Tính năng Facebook (`_features._facebook`)

📝 Đăng bài, đổi tiểu sử, đăng ký mục trên hồ sơ
👤 Tìm kiếm người dùng, lấy thông tin profile, quản lý thông báo
🚫 Chặn / bỏ chặn, quản lý Marketplace và chế độ Professional

Sắp ra mắt

⚡ Hỗ trợ async / await đầy đủ
📦 Phát hành bridge E2EE dưới dạng binary prebuilt cho Windows / Linux / macOS

(*) Đăng nhập bằng cookie / mật khẩu mang theo rủi ro bảo mật; tuyệt đối không chia sẻ token của bạn cho ai.

🏗 Kiến trúc tổng quan

Codebase được chia thành 3 tầng rõ ràng:

Tầng	Đường dẫn	Trách nhiệm
Core	`src/_core/`	Quản lý phiên (session), đăng nhập, request helper, tiện ích cấp thấp
Features	`src/_features/`	Nghiệp vụ Facebook & thread (đăng bài, nhóm, hồ sơ, …)
Messaging	`src/_messaging/`	Gửi / sửa / nhận / react / đổi theme / notes / thu hồi — mọi thứ liên quan đến nhắn tin

flowchart LR
    A[main.py] --> B[_core<br/>session • login • utils]
    B --> C[_features<br/>facebook • thread]
    B --> D[_messaging<br/>send • edit • theme • notes • listen]
    C --> E[(Facebook<br/>endpoints nội bộ)]
    D --> E

📊 Sơ đồ luồng đầy đủ có tại FLOWCHART.md.

📂 Cấu trúc dự án

fbchat-v2/
├── src/
│   ├── main.py                          # Bot mẫu — entry point
│   ├── config.example.json              # Template an toàn cho cấu hình runtime
│   ├── config.json                      # Cookie + cấu hình runtime local (gitignored)
│   ├── _core/                           # ── Tầng nền tảng ──
│   │   ├── _facebookLogin.py
│   │   ├── _session.py
│   │   └── _utils.py
│   ├── _features/                       # ── Tầng tính năng ──
│   │   ├── _facebook/
│   │   │   ├── _blocking.py
│   │   │   ├── _changeBio.py
│   │   │   ├── _createPost.py
│   │   │   ├── _get_user_info.py
│   │   │   ├── _marketplace.py
│   │   │   ├── _notification.py
│   │   │   ├── _professional.py
│   │   │   ├── _registerOnProfile.py
│   │   │   └── _search.py
│   │   └── _thread/
│   │       ├── _addAdmin.py
│   │       ├── _all_thread_data.py
│   │       ├── _changeEmoji.py
│   │       ├── _changeNameThread.py
│   │       └── _changeNickname.py
│   └── _messaging/                      # ── Tầng nhắn tin ──
│       ├── _attachments.py
│       ├── _changeTheme.py              # Đổi theme / nền thread Messenger
│       ├── _createNotes.py              # Messenger Notes (status 24h)
│       ├── _editMessage.py              # Sửa tin nhắn đã gửi qua MQTT LS task
│       ├── _listening.py                # MQTT — tin nhắn nhóm
│       ├── _listening_e2ee.py           # Bridge Go — tin nhắn 1-1 E2EE
│       ├── _message_requests.py
│       ├── _reactions.py
│       ├── _send.py
│       ├── _send_e2ee.py                # Bridge Go — gửi tin nhắn 1-1 E2EE
│       └── _unsend.py
├── bridge-e2ee/                         # ── Bridge Go cho E2EE ──
│   ├── main.go
│   ├── go.mod
│   └── README.md
├── build/                               # Binary `fbchat-bridge-e2ee[.exe]` sau khi `go build`
├── language/
│   └── vi_VN.lang                       # Ngôn ngữ
├── docs/                                # Tài liệu mở rộng
├── DOCS.md
├── FLOWCHART.md
├── CODE_OF_CONDUCT.md
├── LICENSE
└── requirements.txt

Mỗi thư mục con đều có sẵn README.md (tiếng Việt) và README_EN.md (tiếng Anh) mô tả chi tiết từng module.

Mindmap toàn dự án

mindmap
  root((fbchat-v2))
    Tài liệu gốc
      README.md
      README_EN.md
      DOCS.md
      FLOWCHART.md
      CODE_OF_CONDUCT.md
      LICENSE
      requirements.txt
    Mã nguồn (src)
      main.py
      config.example.json
      config.json
      _core
        _facebookLogin.py
        _session.py
        _utils.py
      _features
        _facebook
          _blocking.py
          _changeBio.py
          _createPost.py
          _get_user_info.py
          _marketplace.py
          _notification.py
          _professional.py
          _registerOnProfile.py
          _search.py
        _thread
          _addAdmin.py
          _all_thread_data.py
          _changeEmoji.py
          _changeNameThread.py
          _changeNickname.py
      _messaging
        _attachments.py
        _changeTheme.py
        _createNotes.py
        _editMessage.py
        _listening.py
        _listening_e2ee.py
        _message_requests.py
        _reactions.py
        _send.py
        _send_e2ee.py
        _unsend.py
    Bridge E2EE
      bridge-e2ee/main.go
      build/fbchat-bridge-e2ee
    Ngôn ngữ
      language/vi_VN.lang
    Môi trường
      .venv
      .git

🔧 Yêu cầu hệ thống

Thành phần	Tối thiểu	Khuyến nghị	Ghi chú
Python	3.10	3.11 / 3.12	Bắt buộc
Go (toolchain)	1.24	1.24+	Chỉ cần cho E2EE — để build `fbchat-bridge-e2ee`
Git	bất kỳ	latest	Cần cho `go mod tidy` kéo `mautrix/meta`
Hệ điều hành	Windows / Linux / macOS	—	—
RAM	256 MB	1 GB+	Bridge E2EE chiếm ~80–150 MB khi chạy
Mạng	Kết nối ổn định, không bị chặn `facebook.com` và `edge-chat.facebook.com`	—	—

Các phụ thuộc Python được khai báo trong requirements.txt:

requests>=2.31.0   # HTTP client
paho-mqtt>=1.6.1   # MQTT WebSocket cho _listening.py
attrs>=23.2.0      # Decorator class
pyotp>=2.9.0       # 2FA TOTP khi login bằng username/password

📦 Cài đặt

Tóm tắt: Bước 1–4 bắt buộc cho mọi user. Bước 5 chỉ cần nếu bạn muốn nhận tin nhắn 1-1 (E2EE).

1. Clone mã nguồn

git clone https://github.com/MinhHuyDev/fbchat-v2
cd fbchat-v2

Cách khác: Code → Download ZIP trên GitHub.

2. Tạo môi trường ảo (không bắt buộc nhưng khuyến nghị)

python -m venv .venv

Kích hoạt môi trường:

# Windows (PowerShell)
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

3. Cài đặt phụ thuộc Python

pip install --upgrade pip
pip install -r requirements.txt

Kiểm tra nhanh:

python -c "import requests, paho.mqtt.client, attr, pyotp; print('OK')"

4. Cho phép import từ `src/`

Khi chạy script ở thư mục gốc dự án, hãy expose src/ để các module _core, _features, _messaging được import đúng:

# Windows (PowerShell)
$env:PYTHONPATH = "src"

# macOS / Linux
export PYTHONPATH=src

Hoặc bạn có thể import thủ công với prefix đầy đủ src..

5. (Tuỳ chọn) Build bridge E2EE — cho tin nhắn 1-1

Nếu bạn chỉ cần nhận tin nhắn nhóm, bỏ qua bước này. Ngược lại, tin nhắn cá nhân (E2EE) cần binary Go fbchat-bridge-e2ee.

5.1. Cài Go toolchain

Tải về: https://go.dev/dl/ (Go ≥ 1.24).
Sau khi cài, mở terminal mới và kiểm tra:
```
go version
```

5.2. Kéo source `mautrix/meta`

Repo đã khai báo bridge-e2ee/meta trong .gitmodules, nên ưu tiên dùng submodule:

git submodule update --init --recursive bridge-e2ee/meta

Nếu bạn chỉ build thủ công từ một bản source không có .gitmodules, clone fallback:

cd bridge-e2ee
git clone https://github.com/mautrix/meta.git ./meta

go.mod của bridge-e2ee/ dùng directive replace trỏ tới thư mục ./meta, nên path bridge-e2ee/meta phải tồn tại trước khi go mod tidy / go build.

5.3. Tải dep & build

go mod tidy

# Windows
go build -ldflags="-s -w" -o ../build/fbchat-bridge-e2ee.exe .

# Linux / macOS
go build -ldflags="-s -w" -o ../build/fbchat-bridge-e2ee .

Lần build đầu mất vài phút (~300 MB cache Go module). Sau đó binary khoảng 25–40 MB nằm ở fbchat-v2/build/.

5.4. Verify

cd ..
# Windows
.\build\fbchat-bridge-e2ee.exe --help
# Linux/macOS
./build/fbchat-bridge-e2ee --help

Nếu binary không nằm ở vị trí mặc định, set biến môi trường:

# Windows
$env:FBCHAT_E2EE_BIN = "C:\path\to\fbchat-bridge-e2ee.exe"
# Linux/macOS
export FBCHAT_E2EE_BIN=/path/to/fbchat-bridge-e2ee

Chi tiết thêm: bridge-e2ee/README.md.

6. Cấu hình cookie

Sao chép src/config.example.json thành src/config.json, rồi dán cookie phiên Facebook vào trường cookies. Xem chi tiết ở mục Cấu hình.

7. Smoke test

python src/main.py

Nếu console in ra thông tin tài khoản + last_seq_id, cài đặt đã hoàn tất.

🚀 Bắt đầu nhanh

Một bot demo tối giản đã có sẵn tại src/main.py. File này chứa vài lệnh cơ bản để bạn kiểm tra cài đặt và dùng làm khung mẫu cho bot riêng của mình.

python src/main.py

Trước khi chạy:

Sao chép src/config.example.json thành src/config.json.
Dán cookies Facebook của bạn vào trường cookies.
(Tuỳ chọn) chỉnh các tham số runtime khác trong file.

Bật listener E2EE (tin nhắn 1-1)

E2EE cần binary Go fbchat-bridge-e2ee. Build 1 lần:

git submodule update --init --recursive bridge-e2ee/meta
cd bridge-e2ee
go mod tidy
go build -ldflags="-s -w" -o ../build/fbchat-bridge-e2ee.exe .   # Windows
# Linux/macOS: bỏ đuôi .exe

Sau đó dùng giống _listening.py:

import threading
from _messaging._listening_e2ee import listeningE2EEEvent

listener = listeningE2EEEvent(dataFB)
listener.get_last_seq_id()
threading.Thread(target=listener.connect_mqtt, daemon=True).start()
# listener.bodyResults có schema giống _listening.py

Với listener thường (_listening.py), code mới nên đọc từng event qua listener.get_message() để tránh mất tin khi MQTT callback nhận nhiều delta liên tiếp. bodyResults vẫn giữ snapshot cuối để tương thích ngược.

Override đường dẫn binary qua biến môi trường FBCHAT_E2EE_BIN=/path/to/binary. Chi tiết build & RPC: bridge-e2ee/README.md.

📸 Demo — nhận tin nhắn 1-1 đã giải mã E2EE

Demo: fbchat-v2 nhận tin nhắn cá nhân Messenger qua bridge E2EE

_{Output thực tế của listeningE2EEEvent — bodyResults giữ nguyên schema của _listening.py cũ.}

Sửa tin nhắn, đổi theme và Messenger Notes

Các thao tác Messenger bổ sung nằm ngay trong _messaging và dùng chung dataFB từ _core._session.dataGetHome(...):

from _messaging import _editMessage, _changeTheme, _createNotes

# Sửa tin nhắn đã gửi (thường chỉ sửa được tin do chính tài khoản gửi)
_editMessage.editMessage(dataFB, "mid.$abc...", "Nội dung mới")

# Xem danh sách theme và đổi nền/thread theme
themes = _changeTheme.listThemes(dataFB)
_changeTheme.changeTheme(dataFB, "1234567890", "love")

# Tạo Messenger Note 24h
_createNotes.createNote(dataFB, "Đang code fbchat-v2", privacy="FRIENDS")

Chi tiết API: src/_messaging/README.md và DOCS.md.

⚙️ Cấu hình

src/config.example.json là template được commit. src/config.json là cấu hình runtime local và luôn nằm trong .gitignore.

Khoá	Mô tả
`cookies`	Cookie phiên Facebook của bạn (chuỗi hoặc object). Bắt buộc.
`…`	Các trường khác được mô tả ngay trong file và trong DOCS.md.

🔒 Bảo mật: Hãy coi config.json như một file bí mật. Tuyệt đối không commit lên repo công khai, không chia sẻ cookie cho người khác, và đổi cookie ngay nếu nghi ngờ bị lộ.

📚 Tài liệu từng module

Mỗi tầng đều có README riêng. Hãy bắt đầu từ đó để xem ví dụ API chi tiết:

Module	Tiếng Việt	English
`_core`	`src/_core/README.md`	`src/_core/README_EN.md`
`_features`	`src/_features/README.md`	`src/_features/README_EN.md`
`_messaging`	`src/_messaging/README.md`	`src/_messaging/README_EN.md`
Ngôn ngữ	`language/README.md`	—

Để hiểu thiết kế tổng thể và luồng request đầu-cuối, xem DOCS.md và FLOWCHART.md.

🗺 Lộ trình phát triển

Giải mã E2EE tin nhắn cá nhân Messenger (v2.x — bridge Go)
Sửa tin nhắn, đổi theme thread và Messenger Notes (v2.1.x)
API native async / await
Phân phối bridge E2EE dạng binary prebuilt theo release
Bổ sung type hints cho toàn bộ public API
Storage backend cắm-rút (pluggable) cho session
Bổ sung integration test & CI

Có ý tưởng? Chia sẻ ngay tại Issues.

🤝 Đóng góp

Mọi đóng góp đều được hoan nghênh.

Fork repo và tạo nhánh tính năng:
```
git checkout -b feat/<ten-tinh-nang>
```
Tuân thủ coding style hiện tại và kiến trúc 3 tầng (_core → _features / _messaging).
Dùng Conventional Commits — ví dụ: feat:, fix:, docs:, refactor:.
Mở Pull Request với mô tả rõ ràng, các bước reproduce (với bug fix), kèm screenshot/log nếu cần.
Tuyệt đối không commit thông tin nhạy cảm — config.json, cookie, token, .venv, …

Vui lòng đọc CODE_OF_CONDUCT.md trước khi tham gia.

🌟 Vinh danh người đóng góp

Sau 4 năm phát triển, dự án sẽ không thể tồn tại nếu thiếu cộng đồng. Cảm ơn từ tận đáy lòng tới mọi người đã đóng góp ý tưởng, báo lỗi và giữ cho fbchat còn sống tới ngày hôm nay.

👥 Cộng đồng đóng góp

tomdev112
syrex1013
Kheir Eddine
陶世玉
Jihadi John
Bắc Trịnh
Quang Trần
Minh Trần Ngọc
Victor Knutsenberger
Hoàng Lân
Kareem Adel Abomandor
@lluevy · @phuncnheo · @minhphatnw · @khanh235a · @chapesh1 · @klongg13 · @seafibrahem · @agent1047 · @stefekdziura

🔓 Dự án upstream làm nên v2.1.0 (E2EE)

mautrix/meta — implementation Meta Labyrinth / Lightspeed bằng Go.
tulir/whatsmeow — Signal Protocol (Curve25519, Double Ratchet, Sender Keys, Noise XX) cho ngôn ngữ Go.
yumi-team/meta-messenger.js — tham chiếu thiết kế cho bridge JSON-RPC.
mautrix/go — helper utilities cho client Matrix/Meta.

🤖 Trợ lý AI

Claude Opus 4.7 (Anthropic) — review code, viết tài liệu, refactor-code.
Codex 5.3 (OpenAI) — boilerplate, prototype RPC.

Nếu bạn đã từng đóng góp mà chưa thấy tên ở đây, hãy mở issue hoặc PR — mình rất vinh hạnh được bổ sung bạn vào danh sách.

📜 Bản quyền

Dự án được phân phối theo các điều khoản trong LICENSE. Vui lòng đọc kỹ trước khi sử dụng cho mục đích production hoặc thương mại.

Được làm ❤️ bởi MinhHuyDev · Telegram

Name		Name	Last commit message	Last commit date
Latest commit History 381 Commits
.github		.github
bridge-e2ee		bridge-e2ee
language		language
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
DOCS.md		DOCS.md
FLOWCHART.md		FLOWCHART.md
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
mindmap-mermaid.md		mindmap-mermaid.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

FBChat-Remake — Mã nguồn mở

Thư viện Python hiện đại cho Facebook Messenger API (không chính thức), hoạt động trên tài khoản người dùng

📢 Thông báo quan trọng

👋 Giới thiệu

📑 Mục lục

✨ Tính năng

Xác thực

Nhắn tin

Thread & Nhóm

Tính năng Facebook (_features._facebook)

Sắp ra mắt

🏗 Kiến trúc tổng quan

📂 Cấu trúc dự án

Mindmap toàn dự án

🔧 Yêu cầu hệ thống

📦 Cài đặt

1. Clone mã nguồn

2. Tạo môi trường ảo (không bắt buộc nhưng khuyến nghị)

3. Cài đặt phụ thuộc Python

4. Cho phép import từ src/

5. (Tuỳ chọn) Build bridge E2EE — cho tin nhắn 1-1

5.1. Cài Go toolchain

5.2. Kéo source mautrix/meta

5.3. Tải dep & build

5.4. Verify

6. Cấu hình cookie

7. Smoke test

🚀 Bắt đầu nhanh

Bật listener E2EE (tin nhắn 1-1)

📸 Demo — nhận tin nhắn 1-1 đã giải mã E2EE

Sửa tin nhắn, đổi theme và Messenger Notes

⚙️ Cấu hình

📚 Tài liệu từng module

🗺 Lộ trình phát triển

🤝 Đóng góp

🌟 Vinh danh người đóng góp

👥 Cộng đồng đóng góp

🔓 Dự án upstream làm nên v2.1.0 (E2EE)

🤖 Trợ lý AI

📜 Bản quyền

About

Topics

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases 28

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Tính năng Facebook (`_features._facebook`)

4. Cho phép import từ `src/`

5.2. Kéo source `mautrix/meta`

Packages