WhatsApp 연동
기준일: 2026-07-26
문서 반영 버전: v2026.7.20
난이도: 중급
공식 기준: WhatsApp (Baileys), WhatsApp Business Cloud API, Messaging Overview
Hermes는 WhatsApp에 두 가지 공식 경로를 제공합니다. 개인 실험용 Baileys 브리지와, Meta 공식 Business Cloud API입니다. 둘은 서로 다른 어댑터이며 다른 번호로 동시에 켤 수 있습니다.
핵심 개념
Baileys (hermes whatsapp) |
Cloud API (hermes whatsapp-cloud) |
|
|---|---|---|
| 계정 | 개인 WhatsApp | Meta Business / WABA |
| 설정 | QR 스캔 | Phone Number ID, token, webhook |
| 공개 URL | 불필요 | 필수 (HTTPS webhook) |
| 의존성 | Node.js bridge | Pure Python webhook |
| 밴 리스크 | 있음 (비공식 Web 세션) | 없음 (공식 API) |
| 그룹 | 지원 | v1은 DM 위주 |
| 24시간 창 | 제한 없음 | Meta 고객 서비스 창 (free-form 24h) |
| 적합한 경우 | 개인·데모·단일 사용자 | 비즈 봇·안정 운영 |
Baileys는 WhatsApp Business API가 아닙니다. WhatsApp Web 세션을 에뮬레이션합니다.
선택 기준
- Baileys: 공개 URL 없이 빨리 붙이고, 밴 리스크를 감수한 개인 번호
- Cloud API: 비즈 계정·검증·템플릿 절차를 감수하고 안정적으로 운영
- 전용 번호 사용 권장 (개인 번호에 봇 붙이지 않기)
- allowlist 없이 라이브 금지
실습: Baileys
hermes whatsapp
# 또는
hermes gateway setup # WhatsApp 선택
- bot / self-chat 모드 선택
- 터미널 QR을 WhatsApp → Linked Devices에서 스캔
- 세션은
~/.hermes/platforms/whatsapp/session에 저장
# ~/.hermes/.env
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=15551234567
# WHATSAPP_ALLOWED_USERS=*
# ~/.hermes/config.yaml — 비인가 DM 침묵 (권장: 개인 번호)
whatsapp:
unauthorized_dm_behavior: ignore
hermes gateway
# 재페어링
hermes whatsapp
보안:
chmod 700 ~/.hermes/platforms/whatsapp/session
세션 디렉터리는 계정 전체 접근권과 같으므로 공유·커밋 금지입니다.
실습: Business Cloud API
hermes whatsapp-cloud
위저드가 Phone Number ID, Access Token, App Secret, Verify Token, allowlist를 순서대로 받고 검증합니다.
필수 env (요약):
| 변수 | 의미 |
|---|---|
WHATSAPP_CLOUD_PHONE_NUMBER_ID |
Meta의 15–17자리 ID (전화번호 아님) |
WHATSAPP_CLOUD_ACCESS_TOKEN |
EAA… (프로덕션은 System User permanent token) |
WHATSAPP_CLOUD_APP_SECRET |
webhook 서명 검증 (없으면 inbound 503) |
WHATSAPP_CLOUD_VERIFY_TOKEN |
Meta verify handshake 공유 비밀 |
WHATSAPP_CLOUD_ALLOWED_USERS |
허용 wa_id (국가코드, + 없음) |
공개 HTTPS (예: Cloudflare Tunnel):
cloudflared tunnel --url http://localhost:8090
hermes gateway
# Meta webhook: https://<tunnel>/whatsapp/webhook
curl "$TUNNEL/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=$VERIFY&hub.challenge=hello"
curl http://localhost:8090/health
알려진 제약:
- 사용자 마지막 메시지 후 24시간 지나면 free-form 응답 불가 (error
131047). 템플릿 지원은 공식 문서 기준 미구현·계획 단계 - 개발 모드 Meta recipient whitelist (최대 5번호)와 Hermes allowlist를 둘 다 관리
Hermes에 입력할 프롬프트
개인 테스트용 WhatsApp과 고객 응대용 WhatsApp 중 어떤 Hermes 경로가 맞는지 비교해줘.
allowlist, 공개 URL, 밴 리스크, 24시간 창, 재페어링 절차를 표로 정리하고
최소 검증 명령을 제안해줘.
체크리스트
- Baileys vs Cloud API 중 하나를 목적에 맞게 골랐다.
- 전용 번호(또는 비즈 번호)를 사용한다.
- allowlist를 설정했다 (미설정 시 전원 거부).
- Baileys 세션 디렉터리 권한을 제한했다.
- Cloud API는 Phone Number ID와 전화번호를 혼동하지 않았다.
- Cloud API는 App Secret·permanent token·webhook 검증을 완료했다.
- gateway status와 실제 메시지 송수신을 확인했다.