Wiki · Integrations
WhatsApp has two completely different paths and people mix them up constantly. Which one to choose and what to watch.
📱
WhatsApp has two completely different paths and people mix them up constantly.
The quick bridge (Baileys) behaves like WhatsApp Web on your own number — set up in minutes, no business
account needed, but WhatsApp does not officially support it. The Business Cloud API is the official
route for a company: no ban risk, but a Meta business account, a public HTTPS address and per-conversation
billing.
Which path to choose
| Bridge (Baileys) | Business Cloud API | |
|---|---|---|
| Setup | Minutes — scan a QR code | Hours — Meta app, business portfolio, webhook |
| Account | Your number (ideally a dedicated one) | Meta Business + WhatsApp Business Account |
| Public address | Not needed | HTTPS webhook needed (e.g. Cloudflare Tunnel) |
| Risk | Some risk of account restrictions (unofficial) | None — the official route |
| Cost | Free | Per conversation, per Meta's price list |
| Best for | Your own agent, family, a small team | Customer support, a business |
Path 1: the quick bridge
hermes gateway setup # pick WhatsApp and follow the wizard
The wizard has you scan a QR code (like signing in to WhatsApp Web). From then on the agent answers messages on that number.
| Setting | Meaning |
|---|---|
WHATSAPP_ENABLED | Turns the adapter on |
WHATSAPP_ALLOWED_USERS | Who the agent may answer (international format) |
WHATSAPP_GROUP_POLICY | How to behave in groups |
WHATSAPP_REQUIRE_MENTION | Whether a mention is required in groups |
WHATSAPP_MODE | Bridge mode (see the docs for your version) |
⚠️
Three rules that lower the risk of account restrictions:
use a dedicated number (not your personal one), do not send bulk messages, and do not message
people who have not written first. An agent should converse, not broadcast.
WhatsApp occasionally changes its protocol and the bridge breaks for a while. The fix is usually to update Hermes and re-pair the number — not to hunt for a configuration error.
Path 2: Business Cloud API
hermes whatsapp-cloud # a wizard that validates each value as you paste it
| What you need | Where it comes from |
|---|---|
| Business portfolio and an app with WhatsApp | business.facebook.com, developers.facebook.com |
| Phone Number ID and WABA ID | API Setup in your app |
| Permanent access token (production) | A system user in Meta Business |
| Public HTTPS address for the webhook | Cloudflare Tunnel (free), ngrok, or a reverse proxy on a VPS |
| Webhook verify token | You invent it and paste it on both sides |
| Variable | Purpose |
|---|---|
WHATSAPP_CLOUD_ACCESS_TOKEN | The permanent token |
WHATSAPP_CLOUD_PHONE_NUMBER_ID | The number ID (not the number itself — a common mix-up) |
WHATSAPP_CLOUD_WABA_ID | WhatsApp Business account ID |
WHATSAPP_CLOUD_VERIFY_TOKEN | Webhook verification during registration |
WHATSAPP_CLOUD_ALLOWED_USERS | Who the agent may answer |
The wizard catches the most common trap for you: the Phone Number ID field takes a long numeric ID, not a phone number. Swap them and the API returns an error that looks like a bad token.
What both paths can do
| Feature | Note |
|---|---|
| Text, images, files | Yes, in both modes |
| Voice messages | In the Cloud API an outgoing voice message appears as a proper voice note when ffmpeg is present |
| Groups | The bridge handles them; the Cloud API does not (one-to-one only) |
| Scheduled delivery | Yes — to the home chat (WHATSAPP_CLOUD_HOME_CHANNEL) |
Things to watch
| Situation | What to do |
|---|---|
| A new number gets no answers | It is not in the allowlist; check the number format (international, no spaces) |
| The bridge stopped after a WhatsApp update | Update Hermes and re-pair |
| The Cloud API reports a token error | You are using a test token that expires — deploy the permanent one |
| The webhook will not verify | The verify token does not match, or the address is not reachable over HTTPS |
| Signs of an account restriction | Stop bulk messaging; for a business move to the Cloud API |