WhatsApp Business Cloud API for Rocky

Meta’s official WhatsApp Business Cloud API is the production-oriented WhatsApp path for Hermes Agent. Unlike the unofficial personal-account bridge, it uses HTTPS webhooks and the Graph API, so it needs a public endpoint, a Meta app, and carefully managed credentials.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud

Choose the Cloud path deliberately

Use the Cloud API when business support, official platform status, and a stable production integration matter. The alternative Baileys bridge is easier for personal use and supports groups, but it is unofficial and carries account-ban risk. The Cloud adapter currently focuses on direct messages and is subject to Meta’s 24-hour conversation window.

The guided entry point is hermes whatsapp-cloud. The wizard validates important fields, including the common mistake of entering the visible phone number where Meta expects its internal Phone Number ID.

Production setup checklist

• Create a Meta app and add the WhatsApp product.
• Record the Phone Number ID, not the phone number itself.
• Use a System User token for production rather than a 24-hour test token.
• Store the access token, app secret, and verify token in the active profile’s secret store.
• Expose the webhook through a stable HTTPS endpoint.
• Configure Meta’s callback URL at /whatsapp/webhook.
• Add an explicit Hermes sender allowlist.
• Set a home channel only after inbound and outbound messaging both work.

Security and delivery boundaries

The app secret is used to authenticate inbound webhook signatures. If it is missing, Hermes refuses inbound delivery rather than accepting unsigned requests. The verify token protects the initial webhook handshake, while the sender allowlist controls which WhatsApp identities may trigger agent turns.

Do not use ALLOW_ALL as a shortcut on an internet-reachable bot. Meta’s development recipient list is not a durable substitute for Hermes-side authorization. Keep tokens out of screenshots, shell history, tickets, and wiki examples.

Common pitfalls

• Pasting a phone number into the Phone Number ID field.
• Shipping with a temporary token that expires the next day.
• Using a rotating quick-tunnel URL as if it were a production endpoint.
• Forgetting that free-form outbound messages are restricted after the 24-hour window.
• Assuming Cloud API v1 supports the same group behavior as the personal bridge.
• Treating a successful webhook handshake as proof that signature validation and replies work.

Verification steps

1. Run the guided wizard and restart the gateway.
2. Check the local health endpoint without exposing secret values.
3. Complete Meta’s webhook verification handshake.
4. Send a harmless message from an allowed test number.
5. Confirm an unauthorized sender is denied.
6. Reply within the 24-hour window and verify delivery plus read/typing behavior.
7. Restart the tunnel or service and confirm the public callback URL remains valid.
8. Review gateway logs for signature, authentication, or Graph API errors.

A production-ready WhatsApp connection is not merely “connected.” It has stable credentials, a stable endpoint, a narrow sender policy, and a tested recovery path.