SMS 연동 (Twilio)
기준일: 2026-07-26
난이도: 중급
공식 기준: SMS
개요
Hermes SMS 어댑터는 Twilio 수신 웹훅으로 문자를 받아 회신합니다. 마크다운은 자동 제거, 긴 응답은 1600자 경계에서 분할합니다.
핵심 개념
| 변수 | 필수 | 설명 |
|---|---|---|
TWILIO_ACCOUNT_SID |
Yes | AC… |
TWILIO_AUTH_TOKEN |
Yes | 서명 검증에도 사용 |
TWILIO_PHONE_NUMBER |
Yes | E.164 |
SMS_WEBHOOK_URL |
Yes | Twilio에 등록한 공개 URL과 일치 필수 |
SMS_WEBHOOK_PORT |
No | 기본 8080 |
SMS_WEBHOOK_HOST |
No | 기본 127.0.0.1 |
SMS_INSECURE_NO_SIGNATURE |
No | 로컬 전용 — 프로덕션 금지 |
SMS_ALLOWED_USERS |
권장 | E.164 allowlist |
SMS_ALLOW_ALL_USERS |
No | 비권장 |
SMS_HOME_CHANNEL |
No | cron/알림 번호 |
상세
Twilio 준비
- Twilio 번호 구매
- Messaging webhook:
https://your-server/webhooks/twilio(POST) - 로컬이면 cloudflared/ngrok 터널
cloudflared tunnel --url http://localhost:8080
# SMS_WEBHOOK_URL=https://….trycloudflare.com/webhooks/twilio
게이트웨이
hermes gateway
# [sms] Twilio webhook server listening on 127.0.0.1:8080, from: +1555***4567
SMS_WEBHOOK_URL 없으면 시작 거부.
SMS 동작
- plain text only
- 1600자 분할 (개행→공백)
- 자기 Twilio 번호 echo 무시
- 로그 전화번호 마스킹
보안
X-Twilio-SignatureHMAC 검증- allowlist 기본 권장
- SMS는 전송 구간 E2EE 아님 → 민감 작업은 Signal/Telegram 권장
트러블슈팅
미수신 → 웹훅 URL·공개 접근·SID/토큰·Twilio 로그·allowlist. 미회신 → TWILIO_PHONE_NUMBER E.164·잔액·권한.
체크리스트
- 공식 원문과 명령·설정 키를 대조했다
- 로컬/
config.yaml/.env에서 재현 경로를 확인했다 - 권한·allowlist·시크릿 노출을 점검했다
- 실패 시 롤백·비활성화 방법을 알고 있다
다음 단계
- 공식 문서: SMS
- 메시징 게이트웨이
- Hermes Agent 소개
기준일: 2026-07-26 — 공식 문서 동기화 코퍼스