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.

Unofficial API — Ban Risk

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
WhatsApp Web Protocol Updates

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.

:::tip
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](https://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:

``` bash

# 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 *)

`

:::tip[Allow-all shorthand]
Cài đặt 
`WhatsApp_ALLOWED_USERS=*
` cho phép **tất cả** người gửi (tương đương với 
`WhatsApp_ALLOW_ALL_USERS=true

).
Điều này phù hợp với [Signal group allowlists](/docs/reference/environment-variables).
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
[DM pairing system](/docs/user-guide/security#dm-pairing-system).
:::

Cài đặt hành vi tùy chọn trong 

~/.Hermes/config.yaml

:

``` yaml
unauthoriZed_dm_behavior: pair

WhatsApp:
  unauthoriZed_dm_behavior: ignore

`

- 
`unauthoriZed_dm_behavior: pair
` là mặc định toàn cầu. Người gửi DM không xác định sẽ nhận được mã ghép nối.

- 
`WhatsApp.unauthoriZed_dm_behavior: ignore
` giúp WhatsApp giữ im lặng đối với các DM 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:

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

~/.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ạiNế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ó:

``` bash
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: 
`faster-whisper
` cục bộ, 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

:

``` yaml

# ~/.Hermes/config.yaml
WhatsApp:
  reply_prefix: ""                          # Empty string disables the header
  # reply_prefix: "🤖 *My Bot*\n──────\n"  # Custom prefix (supports \n for newlines)

`

---

## Định dạng và gửi tin nhắn

WhatsApp hỗ trợ **phản hồi phát trực tuyến (liên tục)** — bot chỉnh sửa tin nhắn theo thời gian thực khi AI tạo văn bản, giống như Discord và Telegram. Trong nội bộ, WhatsApp được phân loại là nền tảng TIER_MEDIUM về khả năng phân phối.

### Phân đoạn

Những câu trả lời dài sẽ tự động được chia thành nhiều tin nhắn ở mức **4.096 ký tự** trên mỗi đoạn (giới hạn hiển thị thực tế của WhatsApp). Bạn không cần phải định cấu hình bất cứ điều gì — cổng sẽ xử lý việc phân tách và gửi các khối một cách tuần tự.

### Đánh dấu tương thích với WhatsApp

Markdown tiêu chuẩn trong phản hồi AI được tự động chuyển đổi sang định dạng gốc của WhatsApp:

| Đánh dấu | WhatsApp | Hiển thị dưới dạng |
|----------|----------|-------------|
| 

**bold**
` | 

*bold*
` | **đậm** |
| 

~~strikethrough~~
` | 

~strikethrough~
` | ~~gạch ngang~~ |
| 

# Heading
` | 

*Heading*
` | Văn bản in đậm (không có tiêu đề gốc) |
| 

[link text](url)
` | 
`link text (url)
` | URL nội tuyến |

Các khối mã và mã nội tuyến được giữ nguyên vì WhatsApp vốn đã hỗ trợ định dạng ngược ba lần.

### Tiến trình công cụ

Khi tác nhân gọi các công cụ (tìm kiếm trên web, thao tác tệp, v.v.), WhatsApp sẽ hiển thị các chỉ báo tiến trình theo thời gian thực cho biết công cụ nào đang chạy. Tính năng này được bật theo mặc định - không cần cấu hình.

---

## 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ạn** | Mã 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ục** | Kiể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 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ại** | Khở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 WhatsApp** | Cậ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 terminal** | các dịch vụ launchd không kế thừa shell PATH của bạn. Chạy 
`Hermes gateway install
` để chụp nhanh lại PATH hiện tại của bạn vào phần chính, sau đó là 
`Hermes gateway start

. Xem [Gateway Service docs](./index.md#macOS-launchd) để biết chi tiết. |
| **Không nhận được tin nhắn** | Xá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ối** | Đặt 
`WhatsApp.unauthoriZed_dm_behavior: ignore
` trong 

~/.Hermes/config.yaml
` nếu bạn muốn âm thầm bỏ qua các DM trái phép. |

---

## Bảo mật

:::warning
**Đị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:

``` yaml
WhatsApp:
  unauthoriZed_dm_behavior: ignore

`

- Thư mục 

~/.Hermes/platforms/WhatsApp/session
` chứa thông tin xác thực phiên đầy đủ - 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