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

Cài đặt SMS (Twilio)

Hermes kết nối với SMS thông qua API Twilio. Mọi người nhắn tin vào số điện thoại Twilio của bạn và nhận lại phản hồi từ AI — trải nghiệm trò chuyện tương tự như Telegram hoặc Discord, nhưng qua tin nhắn văn bản tiêu chuẩn.

Shared Credentials

Cổng SMS chia sẻ thông tin đăng nhập với telephony skill tùy chọn. Nếu bạn đã thiết lập Twilio cho các cuộc gọi thoại hoặc SMS một lần thì cổng này sẽ hoạt động với cùng `TWILIO_ACCOUNT_SID

, TWILIO_AUTH_TOKEN và `TWILIO_PHONE_NUMBER

.

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

  • Tài khoản Twilio — Sign up at twilio.com (có bản dùng thử miễn phí)
  • Số điện thoại Twilio có khả năng gửi SMS
  • Một máy chủ có thể truy cập công khai — Twilio gửi webhooks đến máy chủ của bạn khi có SMS đến
  • aiohttp — `pip install 'Hermes-agent[sms]'

Bước 1: Nhận thông tin xác thực Twilio của bạn​

  1. Vào Twilio Console
  2. Sao chép SID tài khoản và Mã thông báo xác thực của bạn từ bảng điều khiển
  3. Đi tới Số điện thoại → Quản lý → Số hoạt động — lưu ý số điện thoại của bạn ở định dạng E.164 (ví dụ:

+15551234567

)

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

Thiết lập tương tác (được khuyến nghị)​

Hermes gateway setup

`
``Chọn **SMS (Twilio)** từ danh sách nền tảng. Trình hướng dẫn sẽ nhắc thông tin xác thực của bạn.

### Thiết lập thủ công

Thêm vào 

~/.Hermes/.env

:

`bash
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

# Security: restrict to specific phone numbers (recommended)
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Optional: set a home channel for cron job delivery
SMS_HOME_CHANNEL=+15559876543

`

---

## Bước 3: Cấu hình Twilio Webhook

Twilio cần biết nơi gửi tin nhắn đến. Trong [Twilio Console](https://console.twilio.com/):
1. Vào **Số điện thoại → Quản lý → Số hoạt động**

2. Nhấp vào số điện thoại của bạn
3. Trong **Tin nhắn → MỘT TIN NHẮN ĐẾN**, hãy đặt:
   - **Webhook**: 
`https://your-server:8080/webhooks/twilio

   - **Phương thức HTTP**: 
`POST

:::tip[Exposing Your Webhook]
Nếu bạn đang chạy Hermes cục bộ, hãy sử dụng đường hầm để hiển thị webhook:

``` bash

# Using cloudflared
cloudflared tunnel --url http://localhost:8080 Using ngrok
ngrok http 8080

`
``Đặt URL công khai kết quả làm webhook Twilio của bạn.
:::

**Đặt 
`SMS_WEBHOOK_URL
` thành cùng một URL mà bạn đã định cấu hình trong Twilio.** Điều này là bắt buộc để xác thực chữ ký Twilio — bộ điều hợp sẽ từ chối khởi động nếu không có nó:

``` bash

# Must match the webhook URL in your Twilio Console
SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio

`
``Cổng webhook mặc định là 
`8080

. Ghi đè bằng:

``` bash
SMS_WEBHOOK_PORT=3000

`

---

## Bước 4: Khởi động Gateway

`bash
Hermes gateway

`
``Bạn nên xem:

`
[sms] Twilio webhook server listening on 127.0.0.1:8080, from: +1555***4567

`
``Nếu bạn thấy 
`Refusing to start: SMS_WEBHOOK_URL is required

, hãy đặt 
`SMS_WEBHOOK_URL
` thành URL công khai được định cấu hình trong Bảng điều khiển Twilio của bạn (xem Bước 3).

Nhắn tin cho số Twilio của bạn - Hermes sẽ trả lời qua SMS.

---

## Biến môi trường

| Biến | Bắt buộc | Mô tả |
|----------|----------|-------------|
| 
`TWILIO_ACCOUNT_SID
` | Có | SID tài khoản Twilio (bắt đầu bằng 
`AC

) |
| 
`TWILIO_AUTH_TOKEN
` | Có | Mã thông báo xác thực Twilio (cũng được sử dụng để xác thực chữ ký webhook) |
| 
`TWILIO_PHONE_NUMBER
` | Có | Số điện thoại Twilio của bạn (định dạng E.164) |
| 
`SMS_WEBHOOK_URL
` | Có | URL công khai để xác thực chữ ký Twilio - phải khớp với URL webhook trong Bảng điều khiển Twilio của bạn |
| 
`SMS_WEBHOOK_PORT
` | Không | Cổng trình nghe Webhook (mặc định: 
`8080

) |
| 
`SMS_WEBHOOK_HOST
` | Không | Địa chỉ liên kết Webhook (mặc định: 
`0.0.0.0

) |
| 
`SMS_INSECURE_NO_SIGNATURE
` | Không | Đặt thành 
`true
` để tắt xác thực chữ ký (chỉ dành cho nhà phát triển cục bộ — **không dành cho sản xuất**) |
| 
`SMS_ALLOWED_USERS
` | Không | Số điện thoại E.164 phân cách bằng dấu phẩy được phép trò chuyện |
| 
`SMS_ALLOW_ALL_USERS
` | Không | Đặt thành 
`true
` để cho phép mọi người (không được khuyến nghị) |
| 
`SMS_HOME_CHANNEL
` | Không | Số điện thoại gửi thông báo/cron job |
| 
`SMS_HOME_CHANNEL_NAME
` | Không | Tên hiển thị cho kênh gia đình (mặc định: 
`Home

) |

---

## Hành vi dành riêng cho SMS
- **Chỉ văn bản thuần túy** — Markdown tự động bị xóa do SMS hiển thị nó dưới dạng ký tự chữ

- **Giới hạn 1600 ký tự** — Các phản hồi dài hơn được chia thành nhiều tin nhắn ở các ranh giới tự nhiên (dòng mới, sau đó là dấu cách)
- **Ngăn chặn tiếng vang** — Tin nhắn từ số Twilio của chính bạn sẽ bị bỏ qua để tránh lặp lại
- **Xóa lại số điện thoại** — Số điện thoại được che giấu trong nhật ký để đảm bảo quyền riêng tư

---

## Bảo mật

### Xác thực chữ ký Webhook

Hermes xác thực rằng các webhook gửi đến thực sự có nguồn gốc từ Twilio bằng cách xác minh tiêu đề 
`X-Twilio-Signature
` (HMAC-SHA1). Điều này ngăn cản kẻ tấn công đưa vào các tin nhắn giả mạo.

**
`SMS_WEBHOOK_URL
` là bắt buộc.** Đặt nó thành URL công khai được định cấu hình trong Bảng điều khiển Twilio của bạn. Bộ chuyển đổi sẽ từ chối khởi động nếu không có nó.

Để phát triển cục bộ không có URL công khai, bạn có thể tắt xác thực:

``` bash

# Local dev only — NOT for production
SMS_INSECURE_NO_SIGNATURE=true

`

### Danh sách cho phép của người dùng**Cổng từ chối tất cả người dùng theo mặc định.** Định cấu hình danh sách cho phép:

``` bash

# Recommended: restrict to specific phone numbers
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Or allow all (NOT recommended for bots with terminal access)
SMS_ALLOW_ALL_USERS=true

`

:::warning
SMS không có mã hóa tích hợp. Không sử dụng SMS cho các hoạt động nhạy cảm trừ khi bạn hiểu được ý nghĩa bảo mật. Đối với các trường hợp sử dụng nhạy cảm, hãy ưu tiên Signal hoặc Telegram.
:::

---

## Khắc phục sự cố

### Tin nhắn không đến
1. Kiểm tra xem URL webhook Twilio của bạn có chính xác và có thể truy cập công khai không
2. Xác minh 
`TWILIO_ACCOUNT_SID
` và 
`TWILIO_AUTH_TOKEN
` là chính xác
3. Kiểm tra Bảng điều khiển Twilio → **Màn hình → Nhật ký → Nhắn tin** để biết lỗi gửi
4. Đảm bảo số điện thoại của bạn nằm trong 
`SMS_ALLOWED_USERS
` (hoặc 
`SMS_ALLOW_ALL_USERS=true

)

### Không gửi thư trả lời
1. Kiểm tra xem 
`TWILIO_PHONE_NUMBER
` đã được đặt chính xác chưa (định dạng E.164 với 

+

)
2. Xác minh tài khoản Twilio của bạn có số hỗ trợ SMS
3. Kiểm tra nhật ký cổng Hermes để tìm lỗi API Twilio

### Xung đột cổng Webhook

Nếu cổng 8080 đã được sử dụng, hãy thay đổi nó:

``` bash
SMS_WEBHOOK_PORT=3001

`
``Cập nhật URL webhook trong Bảng điều khiển Twilio cho phù hợp.