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

BlueBubble (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í 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 ý:

)

  • 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

:

`bash
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:

`
`bash
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

):

`
`bash
BlueBubbles_ALLOWED_USERS=user@icloud.com,+15551234567

`
``**Truy cập mở** (trong 

~/.Hermes/.env

):

`
`bash
BlueBubbles_ALLOW_ALL_USERS=true

`

### 5. Khởi động Gateway

`bash
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ến | Bắt buộc | Mặc định | Mô tả |
|----------|----------|---------|-------------|
| 
`BlueBubbles_SERVER_URL
` | Có | — | URL máy chủ BlueBubbles |
| 
`BlueBubbles_PASSWORD
` | Có | — | Mật khẩu máy chủ |
| 
`BlueBubbles_WEBHOOK_HOST
` | Không |

127.0.0.1
` | Địa chỉ liên kết trình nghe Webhook |
| 
`BlueBubbles_WEBHOOK_PORT
` | Không |

8645
` | Cổng nghe Webhook |
| 
`BlueBubbles_WEBHOOK_PATH
` | Không |

/BlueBubbles-webhook
` | Đường dẫn URL Webhook |
| 
`BlueBubbles_HOME_CHANNEL
` | Không | — | Điện thoại/email để gửi cron |
| 
`BlueBubbles_ALLOWED_USERS
` | Không | — | Người dùng được ủy quyền được phân tách bằng dấu phẩy |
| 
`BlueBubbles_ALLOW_ALL_USERS
` | Không |

false
` | Cho phép tất cả người dùng |

Việc tự động đánh dấu thư là đã đọc được điều khiển bởi khóa 
`send_read_receipts
` trong 
`platforms.BlueBubbles.extra
` trong 

~/.Hermes/config.yaml
` (mặc định: 
`true

). Không có biến môi trường tương ứng.

## 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](https://docs.BlueBubbles.app/helper-bundle/installation).

### 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](https://docs.BlueBubbles.app/helper-bundle/installation):
- 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
- Đảm bảo kết nối mạng (tường lửa, chuyển tiếp cổng)

### 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](https://docs.BlueBubbles.app/helper-bundle/installation)
- 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ó