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 đăng nhập của bạn.

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

Thêm vào ~/.Hermes/.env:

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:

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

# 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ó:

# 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:

SMS_WEBHOOK_PORT=3000

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

Hermes gateway

Bạn nên xem:

[sms] Twilio webhook server listening on 0.0.0.0: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ếnBắt buộcMô tả
TWILIO_ACCOUNT_SIDCóSID tài khoản Twilio (bắt đầu bằng AC)
TWILIO_AUTH_TOKENCó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_NUMBERCóSố điện thoại Twilio của bạn (định dạng E.164)
SMS_WEBHOOK_URLCó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_PORTKhôngCổng trình nghe Webhook (mặc định: 8080)
SMS_WEBHOOK_HOSTKhôngĐịa chỉ liên kết Webhook (mặc định: 0.0.0.0)
SMS_INSECURE_NO_SIGNATUREKhô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_USERSKhôngSố đ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_USERSKhôngĐặt thành true để cho phép mọi người (không được khuyến nghị)
SMS_HOME_CHANNELKhôngSố điện thoại gửi thông báo/cron job
SMS_HOME_CHANNEL_NAMEKhôngTê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:

# Local dev only — NOT for production
SMS_INSECURE_NO_SIGNATURE=true

Danh sách cho phép của người dùngCổ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:​

# 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
cảnh báo

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 được 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ó:

SMS_WEBHOOK_PORT=3001

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