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

Cài đặt WhatsApp

Hermes kết nối với WhatsApp thông qua một cầu nối tích hợp dựa trên Baileys. Tính năng này hoạt động bằng cách mô phỏng phiên Web WhatsApp — không thông qua API WhatsApp Business chính thức. Không yêu cầu tài khoản nhà phát triển Meta hoặc xác minh doanh nghiệp.

API không chính thức — Cấm rủi ro

WhatsApp không chính thức hỗ trợ các bot của bên thứ ba ngoài API doanh nghiệp. Việc sử dụng cầu nối của bên thứ ba có nguy cơ hạn chế tài khoản nhỏ. Để giảm thiểu rủi ro:

  • Sử dụng số điện thoại riêng cho bot (không phải số cá nhân của bạn)
  • Không gửi tin nhắn rác/tin nhắn rác — hãy duy trì việc sử dụng trong cuộc trò chuyện
  • Không tự động nhắn tin đi cho những người chưa nhắn tin trước
Cập nhật giao thức web WhatsApp

WhatsApp cập nhật định kỳ giao thức Web của họ, điều này có thể tạm thời phá vỡ tính tương thích với cầu nối của bên thứ ba. Khi điều này xảy ra, Hermes sẽ cập nhật phần phụ thuộc của bridge. Nếu bot ngừng hoạt động sau khi cập nhật WhatsApp, tải phiên bản Hermes mới nhất và ghép nối lại.

Hai chế độ

Chế độNó hoạt động như thế nàoTốt nhất cho
Số bot riêng (được khuyến nghị)Dành số điện thoại cho bot. Mọi người nhắn tin trực tiếp vào số đó.UX sạch sẽ, nhiều người dùng, rủi ro bị cấm thấp hơn
Tự trò chuyện cá nhânSử dụng WhatsApp của riêng bạn. Bạn nhắn tin cho mình để nói chuyện với đại lý.Thiết lập nhanh, một người dùng, thử nghiệm

Điều kiện tiên quyết

  • Node.js v18+ và npm — cầu WhatsApp chạy dưới dạng quy trình Node.js
  • Điện thoại đã cài đặt WhatsApp (để quét mã QR)

Không giống như các cầu nối dựa trên trình duyệt cũ hơn, cầu nối dựa trên Baileys hiện tại không yêu cầu ngăn xếp phụ thuộc Chrome hoặc Puppeteer cục bộ.

Bước 1: Chạy Setup Wizard

hermes whatsapp

Trình hướng dẫn sẽ:

  1. Hỏi bạn muốn chế độ nào (bot hoặc tự trò chuyện)
  2. Cài đặt các phần phụ thuộc của bridge nếu cần
  3. Hiển thị Mã QR trong terminal của bạn
  4. Đợi bạn quét nó

Để quét mã QR:

  1. Mở WhatsApp trên điện thoại của bạn
  2. Đi tới Cài đặt → Thiết bị được liên kết
  3. Nhấn vào Liên kết thiết bị
  4. Hướng máy ảnh của bạn vào mã QR cuối

Sau khi ghép nối, trình hướng dẫn sẽ xác nhận kết nối và thoát. Phiên của bạn được lưu tự động.

mẹo

Nếu mã QR trông bị cắt xén, hãy đảm bảo terminal của bạn rộng ít nhất 60 cột và hỗ trợ Unicode. Bạn cũng có thể thử trình mô phỏng terminal khác.

Bước 2: Lấy số điện thoại thứ hai (Chế độ Bot)

Đối với chế độ bot, bạn cần có số điện thoại chưa được đăng ký với WhatsApp. Ba lựa chọn:| Tùy chọn | Chi phí | Ghi chú | |--------|------|-------| | Google Voice | Miễn phí | chỉ có ở Mỹ. Nhận số tại voice.google.com. Xác minh WhatsApp qua SMS thông qua ứng dụng Google Voice. | | SIM trả trước | $5–15 một lần | Bất kỳ hãng vận chuyển nào. Kích hoạt, xác minh WhatsApp, sau đó SIM có thể nằm trong ngăn kéo. Số phải luôn hoạt động (thực hiện cuộc gọi 90 ngày một lần). | | Dịch vụ VoIP | Miễn phí–$5/tháng | TextNow, TextFree hoặc tương tự. Một số số VoIP bị WhatsApp chặn — hãy thử một vài số nếu số đầu tiên không hoạt động. |

Sau khi nhận được số:

  1. Cài đặt WhatsApp trên điện thoại (hoặc sử dụng ứng dụng WhatsApp Business với hai SIM)
  2. Đăng ký số mới với WhatsApp
  3. Chạy hermes whatsapp và quét mã QR từ tài khoản WhatsApp đó

Bước 3: Cấu hình Hermes

Thêm phần sau vào tệp ~/.hermes/.env của bạn:

# Required
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          

# "bot" or "self-chat"

# Access control — pick ONE of these options:
WHATSAPP_ALLOWED_USERS=15551234567         

# Comma-separated phone numbers (with country code, no +)
# WHATSAPP_ALLOWED_USERS=*                 

# OR use * to allow everyone
# WHATSAPP_ALLOW_ALL_USERS=true            

# OR set this flag instead (same effect as *)

Viết tắt cho phép tất cả

Cài đặt WHATSAPP_ALLOWED_USERS=* cho phép tất cả người gửi (tương đương WHATSAPP_ALLOW_ALL_USERS=true ). Điều này nhất quán với Danh sách cho phép của nhóm tín hiệu. Thay vào đó, để sử dụng quy trình ghép nối, hãy xóa cả hai biến và dựa vào Hệ thống ghép nối DM.

Cài đặt hành vi tùy chọn trong ~/.hermes/config.yaml :

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

  • unauthorized_dm_behavior: pair là mặc định chung. Người gửi DM không xác định sẽ nhận được mã ghép nối.
  • whatsapp.unauthorized_dm_behavior: ignore khiến WhatsApp giữ im lặng đối với những tin nhắn trực tiếp trái phép, đây thường là lựa chọn tốt hơn cho số riêng tư.

Sau đó khởi động cổng:

hermes gateway              

# Foreground
hermes gateway install      

# Install as a user service
sudo hermes gateway install --system   

# Linux only: boot-time system service

Cổng tự động khởi động cầu WhatsApp bằng phiên đã lưu.

Sự kiên trì của phiên

Cầu Baileys lưu phiên của nó trong ~/.hermes/platforms/whatsapp/session . Điều này có nghĩa là:

  • Phiên vẫn tồn tại khi khởi động lại — bạn không cần phải quét lại mã QR mỗi lần
  • Dữ liệu phiên bao gồm khóa mã hóa và thông tin xác thực thiết bị
  • Không chia sẻ hoặc cam kết thư mục phiên này — nó cấp toàn quyền truy cập vào tài khoản WhatsApp

Ghép nối lại

Nếu phiên bị ngắt (đặt lại điện thoại, cập nhật WhatsApp, hủy liên kết theo cách thủ công), bạn sẽ thấy kết nối lỗi trong nhật ký cổng. Để khắc phục nó:

hermes whatsapp

Điều này tạo ra một mã QR mới. Quét lại và phiên được thiết lập lại. Cửa ngõ tự động xử lý việc ngắt kết nối tạm thời (lỗi mạng, điện thoại ngoại tuyến trong thời gian ngắn) với logic kết nối lại.

Tin nhắn thoại

Hermes hỗ trợ giọng nói trên WhatsApp:

  • Gửi đến: Tin nhắn thoại ( .ogg opus) được chép lời tự động bằng cách sử dụng nhà cung cấp STT đã định cấu hình: local faster-whisper , Groq Whisper ( GROQ_API_KEY ) hoặc OpenAI Whisper ( VOICE_TOOLS_OPENAI_KEY )
  • Gửi đi: Phản hồi TTS được gửi dưới dạng tệp đính kèm tệp âm thanh MP3
  • Phản hồi của nhân viên có tiền tố "⚕ Hermes Agent" theo mặc định. Bạn có thể tùy chỉnh hoặc tắt tính năng này trong config.yaml :
# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          

# Empty string disables the header
  

# reply_prefix: "🤖 *My Bot*\n──────\n"  

# Custom prefix (supports \n for newlines)

Khắc phục sự cố

Vấn đềGiải pháp
Mã QR không quétĐảm bảo terminal đủ rộng (hơn 60 cột). Hãy thử một terminal khác. Đảm bảo bạn đang quét từ đúng tài khoản WhatsApp (số bot, không phải cá nhân).
Mã QR hết hạnMã QR làm mới sau mỗi ~20 giây. Nếu hết thời gian, hãy khởi động lại hermes whatsapp .
Phiên không tiếp tụcKiểm tra xem ~/.hermes/platforms/whatsapp/session có tồn tại và có thể ghi được không. Nếu được chứa trong vùng chứa, hãy gắn nó dưới dạng ổ đĩa bền vững.
Đăng xuất bất ngờWhatsApp hủy liên kết các thiết bị sau thời gian dài không hoạt động. Luôn bật điện thoại và kết nối với mạng, sau đó ghép nối lại với hermes whatsapp nếu cần.
Cầu bị hỏng hoặc vòng lặp kết nối lạiKhởi động lại cổng, cập nhật Hermes và ghép nối lại nếu phiên bị vô hiệu do thay đổi giao thức WhatsApp.
Bot ngừng hoạt động sau khi cập nhật WhatsAppCập nhật Hermes để có phiên bản cầu mới nhất, sau đó ghép lại.
macOS: "Node.js chưa được cài đặt" nhưng nút hoạt động trong terminalcác dịch vụ launchd không kế thừa shell PATH của bạn. Chạy hermes gateway install để chụp lại PATH hiện tại của bạn vào phần chính, sau đó hermes gateway start . Xem Tài liệu dịch vụ cổng để biết chi tiết.
Không nhận được tin nhắnXác minh WHATSAPP_ALLOWED_USERS bao gồm số của người gửi (có mã quốc gia, không có + hoặc dấu cách) hoặc đặt thành * để cho phép mọi người. Đặt WHATSAPP_DEBUG=true trong .env và khởi động lại cổng để xem các sự kiện tin nhắn thô trong bridge.log .
Bot trả lời người lạ bằng mã ghép nốiThay vào đó, hãy đặt whatsapp.unauthorized_dm_behavior: ignore trong ~/.hermes/config.yaml nếu bạn muốn âm thầm bỏ qua các tin nhắn trực tiếp trái phép.

Bảo mật

cảnh báo

Định cấu hình kiểm soát truy cập trước khi phát trực tiếp. Đặt WHATSAPP_ALLOWED_USERS cụ thể số điện thoại (bao gồm mã quốc gia, không có + ), sử dụng * để cho phép mọi người hoặc đặt WHATSAPP_ALLOW_ALL_USERS=true . Nếu không có bất kỳ điều nào trong số này, cổng từ chối tất cả các tin nhắn như một biện pháp an toàn.

Theo mặc định, DM trái phép vẫn nhận được phản hồi mã ghép nối. Nếu bạn muốn số WhatsApp riêng tư hoàn toàn im lặng với người lạ, hãy đặt:

whatsapp:
  unauthorized_dm_behavior: ignore

  • Thư mục ~/.hermes/platforms/whatsapp/session chứa đầy đủ thông tin xác thực phiên — bảo vệ nó như mật khẩu
  • Đặt quyền truy cập tệp: chmod 700 ~/.hermes/platforms/whatsapp/session
  • Sử dụng số điện thoại chuyên dụng cho bot để tách biệt rủi ro khỏi tài khoản cá nhân của bạn
  • Nếu bạn nghi ngờ có sự thỏa hiệp, hãy hủy liên kết thiết bị khỏi WhatsApp → Cài đặt → Thiết bị được liên kết
  • Số điện thoại trong nhật ký được biên tập lại một phần nhưng hãy xem lại chính sách lưu giữ nhật ký của bạn