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

BlueBubbles (iMessage)

Kết nối Hermes với Apple iMessage thông qua BlueBubbles — một máy chủ macOS mã nguồn mở, miễn phí giúp kết nối iMessage với mọi thiết bị.

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

  • Một Mac (luôn bật) chạy BlueBubbles Server
  • ID Apple đã đăng nhập vào Messages.app trên máy Mac đó
  • BlueBubbles Server v1.0.0+ (webhooks yêu cầu phiên bản này)
  • Kết nối mạng giữa Hermes và máy chủ BlueBubbles

Thiết lập​

1. Cài đặt máy chủ BlueBubbles​

Tải xuống và cài đặt từ BlueBubbles.app. Hoàn tất trình hướng dẫn thiết lập — đăng nhập bằng ID Apple của bạn và định cấu hình phương thức kết nối (mạng cục bộ, Ngrok, Cloudflare hoặc DNS động).

2. Lấy URL máy chủ và mật khẩu của bạn​

Trong Máy chủ BlueBubbles → Cài đặt → API, lưu ý:

  • URL máy chủ (ví dụ: http://192.168.1.10:1234)
  • Mật khẩu máy chủ

3. Cấu hình Hermes​

Chạy trình hướng dẫn thiết lập:

Hermes gateway setup

Chọn BlueBubbles (iMessage) và nhập URL máy chủ và mật khẩu của bạn.

Hoặc đặt trực tiếp các biến môi trường trong ~/.Hermes/.env:

BlueBubbles_SERVER_URL=http://192.168.1.10:1234
BlueBubbles_PASSWORD=your-server-password

4. Phân quyền cho người dùng​

Chọn một cách tiếp cận:

Ghép nối DM (được khuyến nghị): Khi ai đó nhắn tin cho iMessage của bạn, Hermes sẽ tự động gửi cho họ mã ghép nối. Phê duyệt nó với:

Hermes pairing approve BlueBubbles <CODE>

Sử dụng Hermes pairing list để xem mã đang chờ xử lý và người dùng được phê duyệt.

Ủy quyền trước cho người dùng cụ thể (trong ~/.Hermes/.env):

BlueBubbles_ALLOWED_USERS=user@icloud.com,+15551234567

Truy cập mở (trong ~/.Hermes/.env):

BlueBubbles_ALLOW_ALL_USERS=true

5. Khởi động Gateway​

Hermes gateway run

Hermes sẽ kết nối với máy chủ BlueBubbles của bạn, đăng ký webhook và bắt đầu nghe tin nhắn iMessage.

Nó hoạt động như thế nào​

iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage
  • Inbound: BlueBubbles gửi sự kiện webhook tới người nghe cục bộ khi có tin nhắn mới. Không bỏ phiếu - giao hàng ngay lập tức.
  • Outbound: Hermes gửi tin nhắn qua BlueBubbles REST API.
  • Phương tiện: Hình ảnh, tin nhắn thoại, video và tài liệu được hỗ trợ theo cả hai hướng. Các tệp đính kèm gửi đến được tải xuống và lưu vào bộ nhớ đệm cục bộ để tổng đài viên xử lý.

Biến môi trường​

BiếnBắt buộcMặc địnhMô tả
BlueBubbles_SERVER_URLCó—URL máy chủ BlueBubbles
BlueBubbles_PASSWORDCó—Mật khẩu máy chủ
BlueBubbles_WEBHOOK_HOSTKhông127.0.0.1Địa chỉ liên kết trình nghe Webhook
BlueBubbles_WEBHOOK_PORTKhông8645Cổng nghe Webhook
BlueBubbles_WEBHOOK_PATHKhông/BlueBubbles-webhookĐường dẫn URL Webhook
BlueBubbles_HOME_CHANNELKhông—Điện thoại/email để gửi cron
BlueBubbles_ALLOWED_USERSKhông—Người dùng được ủy quyền được phân tách bằng dấu phẩy
BlueBubbles_ALLOW_ALL_USERSKhôngfalseCho phép tất cả người dùng
BlueBubbles_SEND_READ_RECEIPTSKhôngtrueTự động đánh dấu thư là đã đọc

Tính năng​

Nhắn tin văn bản​

Gửi và nhận iMessages. Markdown được tự động loại bỏ để phân phối văn bản thuần túy rõ ràng.

Đa phương tiện​

  • Hình ảnh: Ảnh xuất hiện tự nhiên trong cuộc trò chuyện iMessage
  • Tin nhắn thoại: Tệp âm thanh được gửi dưới dạng tin nhắn thoại iMessage
  • Video: Tệp đính kèm video
  • Tài liệu: Tệp được gửi dưới dạng tệp đính kèm iMessage

Phản ứng Tapback​

Yêu, thích, không thích, cười, nhấn mạnh và đặt câu hỏi phản ứng. Yêu cầu BlueBubbles Private API helper.

Chỉ báo gõ​

Hiển thị "đang gõ..." trong cuộc trò chuyện iMessage trong khi tổng đài viên đang xử lý. Yêu cầu API riêng tư.

Đã đọc Biên lai​

Tự động đánh dấu tin nhắn là đã đọc sau khi xử lý. Yêu cầu API riêng tư.

Địa chỉ trò chuyện​

Bạn có thể giải quyết các cuộc trò chuyện bằng email hoặc số điện thoại - Hermes tự động phân giải chúng thành GUID trò chuyện BlueBubbles. Không cần sử dụng định dạng GUID thô.

API riêng tư​

Một số tính năng yêu cầu BlueBubbles Private API helper:

  • Phản ứng tapback
  • Chỉ báo gõ
  • Đọc biên lai
  • Tạo cuộc trò chuyện mới theo địa chỉ

Nếu không có API riêng tư, tính năng nhắn tin văn bản và phương tiện cơ bản vẫn hoạt động.

Khắc phục sự cố​

"Không thể truy cập máy chủ"​

  • Xác minh URL máy chủ là chính xác và máy Mac đang bật
  • Kiểm tra xem BlueBubbles Server có đang chạy không
  • Ensure network connectivity (firewall, port forwarding)

Tin nhắn không đến​

  • Kiểm tra xem webhook đã được đăng ký trong BlueBubbles Server chưa → Cài đặt → API → Webhooks
  • Xác minh URL webhook có thể truy cập được từ máy Mac
  • Kiểm tra Hermes logs gateway để tìm lỗi webhook (hoặc Hermes logs -f để theo dõi trong thời gian thực)### "Trình trợ giúp API riêng tư chưa được kết nối"
  • Cài đặt trình trợ giúp API riêng: docs.BlueBubbles.app
  • Nhắn tin cơ bản hoạt động mà không cần nó - chỉ có các phản ứng, đánh máy và xác nhận đã đọc mới yêu cầu nó