Baileys: Thư viện TypeScript cho WhatsApp Web API
WhiskeySockets/Baileys
Baileys là thư viện TypeScript kết nối tới WhatsApp Web qua WebSocket bằng cách reverse-engineer giao thức, thay vì gọi một API chính thức của WhatsApp. Hãy dùng Baileys nếu bạn muốn toàn quyền kiểm soát việc nhắn tin WhatsApp bằng code, miễn phí, và chấp nhận được các breaking changes như ở bản v7.0.0; bỏ qua nếu bạn cần một tích hợp được nhà cung cấp hậu thuẫn chính thức, vì nhóm phát triển tuyên bố rõ không liên kết với WhatsApp.
Baileys là gì?
Baileys là thư viện TypeScript dựa trên WebSocket dùng để tương tác với WhatsApp Web API, được phân phối trên npm dưới tên gói baileys. Baileys kết nối qua socket thay vì bọc quanh SDK của bên thứ ba, và chính bản disclaimer của dự án nói rõ không liên kết, không được WhatsApp xác nhận hay bảo trợ. Repo được gắn topic cho Node.js, Bun, Deno và reverse-engineering trên GitHub, và phát hành theo giấy phép MIT.
Tính năng và khả năng cốt lõi
- ✓Kết nối tới WhatsApp Web qua một kết nối WebSocket thuần (socket-based, đúng theo mô tả của repo) thay vì điều khiển một trình duyệt.
- ✓Viết bằng TypeScript, nên các dự án dùng Baileys nhận được type cho các đối tượng message và event thay vì JavaScript lỏng lẻo.
- ✓Chạy được trên nhiều runtime — Node.js, Bun và Deno — theo đúng các topic mà repo tự gắn trên GitHub.
- ✓Cấp phép theo giấy phép MIT, nên mã nguồn được tự do sử dụng, chỉnh sửa và phân phối lại.
- ✓Được versioning tích cực, đã qua bản v7.0.0 với nhiều breaking changes, kèm hướng dẫn migrate riêng tại whiskey.so/migrate-latest.
- ✓Có cộng đồng Discord WhiskeySockets đang hoạt động để hỗ trợ và thảo luận, được README dẫn link trực tiếp.
Bắt đầu sử dụng và tài liệu hướng dẫn
Baileys dẫn người dùng tới hai nguồn tài liệu: guide mới tại baileys.wiki, được chính README ghi chú là work in progress với các trang còn thiếu, và guide cũ nằm ngay trong README.md trên nhánh master của repo hoặc trên trang npm (npmjs.com/package/baileys). Muốn hỗ trợ trực tiếp, README dẫn tới cộng đồng Discord WhiskeySockets tại whiskey.so/discord. Vì v7.0.0 mang theo nhiều breaking changes, README khuyến nghị đọc hướng dẫn migrate tại whiskey.so/migrate-latest trước khi nâng cấp.
Điểm mạnh
- ✓Cấp phép MIT — tự do fork, chỉnh sửa và nhúng vào dự án thương mại.
- ✓Ưu tiên TypeScript, nên người dùng có type ở compile-time cho API socket/event thay vì làm việc với JS lỏng lẻo kiểu dữ liệu.
- ✓Đa runtime: topic của repo liệt kê hỗ trợ Node.js, Bun và Deno.
- ✓Có kênh cộng đồng hoạt động (Discord) cộng với lựa chọn hỗ trợ trả phí trực tiếp từ maintainer cho team cần.
- ✓Được bảo trì đủ tích cực để ra một bản breaking-change lớn (v7.0.0) kèm guide migrate riêng, thay vì bị bỏ rơi.
Lưu ý quan trọng và cân nhắc khi sử dụng
- △Không được WhatsApp chính thức liên kết hay xác nhận — chính disclaimer của README nói rõ điều này và cảnh báo về rủi ro khi vi phạm Terms of Service, kéo theo rủi ro bị khoá tài khoản cho ai triển khai nó.
- △Bản v7.0.0 mang theo nhiều breaking changes (được đánh dấu CAUTION rõ ràng), nên việc nâng cấp đòi hỏi làm theo hướng dẫn migrate chứ không phải chỉ bump version.
- △Trang tài liệu mới tại baileys.wiki tự ghi là work in progress với các trang và nội dung còn thiếu, theo đúng ghi chú IMPORTANT trong README.
- △Hỗ trợ ở mức doanh nghiệp không nằm trong issue tracker của dự án — đó là một buổi gọi 1 giờ trả phí với maintainer, đặt qua Discord hoặc purpshell.dev/book, chứ không phải hợp đồng hỗ trợ hay SLA.
Baileys phù hợp với ai?
Baileys phù hợp với lập trình viên quen TypeScript và Node.js, muốn toàn quyền kiểm soát ở tầng code cho việc nhắn tin WhatsApp và chấp nhận rủi ro mà chính disclaimer của README nêu ra. Đây không phải lựa chọn đúng cho team cần một kênh được nhà cung cấp bảo chứng hợp đồng — điều đó đòi hỏi trả phí trực tiếp cho maintainer hoặc tìm giải pháp khác.
Lựa chọn thay thế cho Baileys
Câu hỏi thường gặp
Baileys được phát hành theo giấy phép MIT, bản quyền thuộc Rajeh Taher/WhiskeySockets, cho phép sử dụng, chỉnh sửa và phân phối lại tự do, kể cả trong dự án thương mại.
Baileys không chính thức liên kết với WhatsApp: chính disclaimer trong README nói rõ dự án không liên kết, không được WhatsApp hay các công ty con của WhatsApp cho phép hay bảo trợ.
Có — README của Baileys đánh dấu bản v7.0.0 bằng cảnh báo CAUTION về nhiều breaking changes, và dẫn tới hướng dẫn migrate riêng tại whiskey.so/migrate-latest cho ai cần nâng cấp.
Tài liệu của Baileys nằm ở hai nơi: guide mới tại baileys.wiki (đang work in progress), và README.md / trang npm cũ (npmjs.com/package/baileys) cho phần nội dung chưa được chuyển sang guide mới.
Maintainer hiện tại của Baileys, Rajeh, cung cấp buổi gọi hỗ trợ trả phí 1 giờ ở mức doanh nghiệp, đặt lịch qua Discord hoặc purpshell.dev/book, thay vì một hợp đồng hỗ trợ chính thức hay SLA.
README của Baileys yêu cầu người dùng hành xử có trách nhiệm: không khuyến khích spam, stalkerware hay nhắn tin hàng loạt/tự động, và nói rõ maintainer không dung túng việc dùng thư viện để vi phạm Terms of Service của WhatsApp.
Vấn đề mà Baileys giải quyết
Lập trình viên muốn gửi và nhận tin nhắn WhatsApp bằng code gặp một rào cản: WhatsApp không công bố API công khai cho WhatsApp Web dành cho người dùng, chỉ có giao diện chat chính thức chạy trong trình duyệt. Baileys giải quyết đúng khoảng trống đó bằng cách reverse-engineer giao thức WebSocket mà chính WhatsApp Web dùng, để một tiến trình Node.js/TypeScript có thể mở thẳng kết nối socket đó thay vì phải tự động hoá một trình duyệt headless.
Trường hợp sử dụng tốt nhất
- •Xây bot WhatsApp hoặc kịch bản tự động hoá nhắn tin chạy trực tiếp bằng code TypeScript/Node.js.
- •Chuyển tiếp thông báo hoặc cảnh báo qua WhatsApp từ một backend có sẵn.
- •Tích hợp nhắn tin WhatsApp vào một dịch vụ chat với khách hàng tự viết.
- •Thử nghiệm ở tầng giao thức WebSocket của WhatsApp Web cho mục đích nghiên cứu hoặc reverse-engineering.
Cách cài đặt / dùng thử
Bundle facts không cho một lệnh cài đặt cụ thể — README dẫn người dùng tới trang npm của gói (npmjs.com/package/baileys) và tới guide riêng tại baileys.wiki hoặc README.md cũ trên nhánh master, chứ không in sẵn lệnh npm install trong đoạn trích được cung cấp. Vì vậy bước cài đặt chính xác không được tài liệu hoá rõ ràng trong nguồn này — hãy theo các link đó để lấy hướng dẫn mới nhất.