WhatsApp 설정

Hermes는 Baileys 기반 내장 bridge를 통해 WhatsApp에 연결합니다. 이 방식은 공식 WhatsApp Business API가 아니라 WhatsApp Web session을 emulate합니다. Meta developer account나 Business verification은 필요 없습니다.

Unofficial API - Ban Risk

WhatsApp은 Business API 밖의 third-party bot을 공식 지원하지 않습니다. Third-party bridge를 사용하면 계정 제한 위험이 작게나마 있습니다. 위험을 줄이려면 다음을 지키세요.

• Bot에는 전용 phone number를 사용하세요. 개인 번호를 쓰지 않는 것이 좋습니다.
• Bulk/spam message를 보내지 마세요. 대화형 사용에 머무르세요.
• 먼저 메시지를 보낸 적 없는 사람에게 outbound message를 자동화하지 마세요.

WhatsApp Web Protocol Updates

WhatsApp은 Web protocol을 주기적으로 업데이트하며, 이때 third-party bridge 호환성이 일시적으로 깨질 수 있습니다. 이런 일이 생기면 Hermes가 bridge dependency를 업데이트합니다. WhatsApp 업데이트 뒤 bot이 멈췄다면 최신 Hermes로 업데이트한 뒤 다시 pair하세요.

Two Modes

Mode	How it works	Best for
Separate bot number(권장)	Bot 전용 phone number를 둡니다. 사용자는 그 번호로 직접 메시지를 보냅니다.	깔끔한 UX, 여러 사용자, 낮은 ban risk
Personal self-chat	자신의 WhatsApp을 그대로 사용합니다. 자신에게 메시지를 보내 agent와 대화합니다.	빠른 setup, 단일 사용자, 테스트

Prerequisites

• **Node.js v18+**와 npm - WhatsApp bridge는 Node.js process로 실행됩니다.
• WhatsApp이 설치된 phone - QR code를 scan하는 데 필요합니다.

예전의 browser-driven bridge와 달리, 현재 Baileys 기반 bridge는 local Chromium이나 Puppeteer dependency stack이 필요하지 않습니다.

1단계: Setup wizard 실행

hermes whatsapp

Wizard는 다음을 수행합니다.

1. 사용할 mode를 묻습니다. bot 또는 self-chat.
2. 필요한 경우 bridge dependency를 설치합니다.
3. Terminal에 QR code를 표시합니다.
4. 사용자가 scan할 때까지 기다립니다.

QR code scan 방법:

1. Phone에서 WhatsApp을 엽니다.
2. Settings -> Linked Devices로 이동합니다.
3. Link a Device를 누릅니다.
4. Camera로 terminal QR code를 scan합니다.

Pairing이 끝나면 wizard가 연결을 확인하고 종료합니다. Session은 자동 저장됩니다.

팁

QR code가 깨져 보이면 terminal 폭이 최소 60 columns인지, Unicode를 지원하는지 확인하세요. 다른 terminal emulator를 사용해 보는 것도 좋습니다.

2단계: 두 번째 phone number 준비하기(Bot mode)

Bot mode에서는 아직 WhatsApp에 등록되지 않은 phone number가 필요합니다. 선택지는 세 가지입니다.

Option	Cost	Notes
Google Voice	Free	미국 전용입니다. voice.google.com에서 번호를 받고, Google Voice app의 SMS로 WhatsApp을 verify합니다.
Prepaid SIM	일회성 $5-25	아무 carrier나 가능합니다. Activate하고 WhatsApp을 verify한 뒤 SIM은 보관해도 됩니다. 번호는 계속 active여야 합니다. 예를 들어 90일마다 한 번 통화하세요.
VoIP services	Free-$5/month	TextNow, TextFree 등입니다. 일부 VoIP number는 WhatsApp이 차단합니다. 처음 것이 안 되면 몇 가지를 시도해야 할 수 있습니다.

번호를 준비한 뒤:

1. Phone에 WhatsApp을 설치합니다. Dual-SIM이면 WhatsApp Business app을 써도 됩니다.
2. 새 번호를 WhatsApp에 등록합니다.
3. hermes whatsapp을 실행하고 그 WhatsApp account에서 QR code를 scan합니다.

3단계: Hermes 설정

~/.hermes/.env에 다음 값을 추가합니다.

# Required
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" or "self-chat"

# Access control - 아래 옵션 중 하나를 선택
WHATSAPP_ALLOWED_USERS=15551234567         # 국가 코드 포함, + 없이 comma-separated phone numbers
# WHATSAPP_ALLOWED_USERS=*                 # 모든 sender 허용
# WHATSAPP_ALLOW_ALL_USERS=true            # *와 같은 효과

Allow-all shorthand

WHATSAPP_ALLOWED_USERS=*를 설정하면 모든 sender를 허용합니다. 이는 WHATSAPP_ALLOW_ALL_USERS=true와 같습니다. Signal group allowlists와 같은 규칙입니다. Pairing flow를 사용하려면 두 변수를 모두 제거하고 DM pairing system에 맡기세요.

~/.hermes/config.yaml에서 optional behavior도 설정할 수 있습니다.

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

• unauthorized_dm_behavior: pair는 global default입니다. Unknown DM sender는 pairing code를 받습니다.
• whatsapp.unauthorized_dm_behavior: ignore는 WhatsApp에서 unauthorized DM을 조용히 무시하게 합니다. Private number에는 보통 이 설정이 더 적합합니다.

그다음 gateway를 시작합니다.

hermes gateway              # Foreground
hermes gateway install      # User service로 설치
sudo hermes gateway install --system   # Linux only: boot-time system service

Gateway는 저장된 session을 사용해 WhatsApp bridge를 자동으로 시작합니다.

Session Persistence

Baileys bridge는 session을 ~/.hermes/platforms/whatsapp/session 아래에 저장합니다. 의미는 다음과 같습니다.

• Restart 후에도 session이 유지됩니다. 매번 QR code를 다시 scan할 필요가 없습니다.
• Session data에는 encryption key와 device credential이 들어 있습니다.
• 이 session directory를 공유하거나 commit하지 마세요. WhatsApp account에 대한 전체 access를 부여하는 정보입니다.

Re-pairing

Phone reset, WhatsApp update, 수동 unlink 등으로 session이 깨지면 gateway log에서 connection error가 보입니다. 해결하려면 다음을 실행하세요.

hermes whatsapp

새 QR code가 생성됩니다. 다시 scan하면 session이 재설정됩니다. Gateway는 network blip이나 phone이 잠깐 offline이 되는 temporary disconnection은 reconnection logic으로 자동 처리합니다.

Voice Messages

Hermes는 WhatsApp voice를 지원합니다.

• Incoming: Voice message(.ogg opus)는 설정된 STT provider로 자동 전사됩니다. Provider는 local faster-whisper, Groq Whisper(GROQ_API_KEY), OpenAI Whisper(VOICE_TOOLS_OPENAI_KEY)를 사용할 수 있습니다.
• Outgoing: TTS response는 MP3 audio file attachment로 전송됩니다.
• Agent response는 기본적으로 🤖 **Hermes Agent** prefix가 붙습니다. config.yaml에서 바꾸거나 끌 수 있습니다.

# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          # 빈 문자열은 header를 비활성화
  # reply_prefix: "🤖 *My Bot*\n────────\n"  # Custom prefix(\n newline 지원)

Message Formatting & Delivery

WhatsApp은 streaming(progressive) response를 지원합니다. Discord와 Telegram처럼 AI가 text를 생성하는 동안 bot이 메시지를 실시간으로 edit합니다. 내부적으로 WhatsApp은 delivery capability가 TIER_MEDIUM인 platform으로 분류됩니다.

Chunking

긴 response는 chunk당 4,096자 기준으로 여러 메시지로 자동 분할됩니다. 이는 WhatsApp의 실질적인 표시 한계입니다. 따로 설정할 것은 없습니다. Gateway가 분할하고 순서대로 전송합니다.

WhatsApp-Compatible Markdown

AI response의 표준 Markdown은 WhatsApp native formatting으로 자동 변환됩니다.

Markdown	WhatsApp	Renders as
**bold**	*bold*	bold
~~strikethrough~~	~strikethrough~	strikethrough
# Heading	*Heading*	Bold text. WhatsApp에는 native heading이 없습니다.
[link text](url)	link text (url)	Inline URL

Code block과 inline code는 그대로 유지됩니다. WhatsApp이 triple-backtick formatting을 native로 지원하기 때문입니다.

Tool Progress

Agent가 web search, file operation 같은 tool을 호출하면 WhatsApp은 어떤 tool이 실행 중인지 보여 주는 real-time progress indicator를 표시합니다. 기본적으로 enabled이며 별도 설정은 필요 없습니다.

Troubleshooting

Problem	Solution
QR code가 scan되지 않음	Terminal 폭이 충분한지 확인하세요(60+ columns). 다른 terminal을 시도하세요. 올바른 WhatsApp account에서 scan하는지도 확인하세요. Bot number여야 하며 personal number가 아닐 수 있습니다.
QR code가 만료됨	QR code는 약 20초마다 refresh됩니다. Timeout되면 hermes whatsapp을 다시 시작하세요.
Session이 유지되지 않음	~/.hermes/platforms/whatsapp/session이 존재하고 writable인지 확인하세요. Containerized 환경이면 persistent volume으로 mount하세요.
예상치 못하게 logout됨	WhatsApp은 장기간 inactivity 후 linked device를 unlink할 수 있습니다. Phone을 켜고 network에 연결한 뒤 필요하면 hermes whatsapp으로 다시 pair하세요.
Bridge crash 또는 reconnect loop	Gateway를 restart하고 Hermes를 업데이트하세요. WhatsApp protocol change로 session이 invalidated되었다면 re-pair하세요.
WhatsApp update 뒤 bot이 멈춤	최신 bridge version을 받기 위해 Hermes를 업데이트한 뒤 re-pair하세요.
macOS: terminal에서는 node가 되는데 "Node.js not installed"가 뜸	launchd service는 shell PATH를 inherit하지 않습니다. hermes gateway install을 다시 실행해 현재 PATH를 plist에 snapshot한 뒤 hermes gateway start를 실행하세요. 자세한 내용은 Gateway Service docs를 참고하세요.
Message를 받지 못함	WHATSAPP_ALLOWED_USERS에 sender 번호가 포함되어 있는지 확인하세요. 국가 코드를 포함하고 +나 space는 빼야 합니다. 모두 허용하려면 *로 설정하세요. .env에 WHATSAPP_DEBUG=true를 설정하고 gateway를 restart하면 bridge.log에서 raw message event를 볼 수 있습니다.
Bot이 stranger에게 pairing code를 보냄	Unauthorized DM을 조용히 무시하려면 ~/.hermes/config.yaml에 whatsapp.unauthorized_dm_behavior: ignore를 설정하세요.

Security

경고

Live로 사용하기 전에 access control을 반드시 설정하세요. 국가 코드를 포함하고 + 없이 phone number를 넣은 WHATSAPP_ALLOWED_USERS를 설정하거나, *로 모두 허용하거나, WHATSAPP_ALLOW_ALL_USERS=true를 설정하세요. 이 중 아무것도 없으면 gateway는 안전을 위해 모든 incoming message를 거부합니다.

기본적으로 unauthorized DM은 pairing code reply를 받습니다. Private WhatsApp number가 stranger에게 완전히 조용히 있기를 원한다면 다음을 설정하세요.

whatsapp:
  unauthorized_dm_behavior: ignore

• ~/.hermes/platforms/whatsapp/session directory에는 전체 session credential이 들어 있습니다. Password처럼 보호하세요.
• File permission을 제한하세요: chmod 700 ~/.hermes/platforms/whatsapp/session
• Personal account risk를 분리하려면 bot 전용 phone number를 사용하세요.
• Compromise가 의심되면 WhatsApp Settings -> Linked Devices에서 device를 unlink하세요.
• Log의 phone number는 일부 redacted되지만, log retention policy를 검토하세요.