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.

Thông tin xác thực được chia sẻ

Cổng SMS chia sẻ thông tin xác thực với kỹ năng điện thoại 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 — Đăng ký tại 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. Đi tới Bảng điều khiển Twilio
  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 :

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 Bảng điều khiển Twilio:

  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 Nhắn tin → MỘT TIN NHẮN ĐẾN, hãy đặt:
    • Webhook: https://your-server:8080/webhooks/twilio
    • Phương thức HTTP: POST
Hiển thị Webhook của bạn

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.

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 port 8080, from: +1555***4567

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
TWILIO_PHONE_NUMBERCóSố điện thoại Twilio của bạn (định dạng E.164)
SMS_WEBHOOK_PORTKhôngCổng trình nghe Webhook (mặc định: 8080 )
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 chủ (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

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:

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