5.4. WhatsApp — Two Integration Paths
Baileys bridge (default) vs. Business Cloud API
- Default bridge: the installer automatically downloads Node.js 22 to run the WhatsApp bridge right at install time — scan the QR code with your phone and you are done, no additional registration with Meta needed.
- WhatsApp Business Cloud API (added in v0.17.0): a second, webhook-style adapter that does not require “keeping alive” a background bridge — suitable when you need higher stability for business use cases.
The important limit: one phone number = one profile
This is a technical constraint to know before planning: each Hermes profile needs its own phone number/WhatsApp session — you cannot attach multiple profiles to different conversations on the same number, because the Baileys bridge uses a single authentication session per number.
Alternatives if you need “many roles” on the same number
- Use a single profile and switch personalities via
/personality(7.1) or different AGENTS.md files per context — the agent figures out which conversation it is in and adjusts. - For repetitive specialized tasks (for example, tracking a shopping list in a specific chat), use a dedicated monitoring cron job instead of trying to split it into an independent agent.
- If you truly need fully separate agents, use a different phone number for each profile.
Notes
- For personal/experimental use cases, the Baileys bridge (QR scan) is enough and the fastest way to get started.
- For business use cases that need high reliability (no worry about the bridge randomly disconnecting), consider the Business Cloud API even though registration is more complex.
- Before planning multiple profiles on WhatsApp, always remember the one-number-one-profile limit — avoid designing an architecture based on a false assumption.