Blog / channel guide

Hermes Agent on WhatsApp Business Cloud API

There are two ways to put Hermes Agent on WhatsApp, and they are not equivalent. Meta's official WhatsApp Business Cloud API uses a business account and a dedicated number, needs no bridge process and carries no ban risk, but it requires a public webhook and follows Meta's messaging rules. The QR-based bridge is quicker for personal use and is the riskier of the two.

Updated Sep 15, 20268 min read

Deployment route

01
Create a Meta business account and app
Create the business account, then create an app with the WhatsApp use case so you get a WhatsApp Business Account linked to it.
02
Attach a dedicated business number
Use a number that is not already active on a personal WhatsApp account. The bot needs its own identity, and moving an existing number is painful.
03
Collect the identifiers carefully
Note the phone number ID rather than the phone number itself, plus the business account ID and an access token. Confusing the number with its ID is the most common setup mistake.
04
Expose and register an HTTPS webhook
Meta delivers inbound messages to a public HTTPS endpoint, so provide a hostname with a valid certificate and register it with the verification token.
05
Subscribe the app to message events
Subscribe the app to the messages field so inbound text, media, and status updates reach the gateway instead of disappearing silently.
06
Test inside the 24-hour window
Send a message from a phone and confirm a reply. Replies inside the 24-hour service window need no template, which is why the first test should happen immediately.

Four-step path

How do you deploy Hermes Agent on the WhatsApp Cloud API?

Five checkpoints: set up the business account and number, collect the identifiers, expose an HTTPS webhook, subscribe the app to messages, then test inside the reply window.

Step 01
Create a Meta business account and app
Create the business account, then create an app with the WhatsApp use case so you get a WhatsApp Business Account linked to it.
Step 02
Attach a dedicated business number
Use a number that is not already active on a personal WhatsApp account. The bot needs its own identity, and moving an existing number is painful.
Step 03
Collect the identifiers carefully
Note the phone number ID rather than the phone number itself, plus the business account ID and an access token. Confusing the number with its ID is the most common setup mistake.
Step 04
Expose and register an HTTPS webhook
Meta delivers inbound messages to a public HTTPS endpoint, so provide a hostname with a valid certificate and register it with the verification token.
Step 05
Subscribe the app to message events
Subscribe the app to the messages field so inbound text, media, and status updates reach the gateway instead of disappearing silently.
Step 06
Test inside the 24-hour window
Send a message from a phone and confirm a reply. Replies inside the 24-hour service window need no template, which is why the first test should happen immediately.

Should you use the Cloud API or the QR bridge?

Use the Cloud API for anything customer-facing or long-lived, and use the bridge only for personal experiments where the risk of losing the number is acceptable.

Cloud API: official, no bridge process, no QR session to keep alive.
Cloud API: needs a business account, a dedicated number, and a public webhook.
Bridge: works with a personal account and needs no public URL, but is unofficial.
Bridge: an automated account can be restricted, which is a real business risk.

Compare the QR session setup

Do you need a separate number?

Yes. The Cloud API is designed for a business identity, and the bot should not run on the number a person uses for personal chats.

A number already active on personal WhatsApp usually has to be removed first.
Display name and business profile are visible to anyone who messages the bot.
Keep test and production numbers separate so experiments do not touch customers.
Number quality affects messaging limits, so how you use it matters over time.

Why do replies stop working after a day?

Because Meta only allows free-form replies inside a 24-hour window after the user's last message. After that, you need a pre-approved template to start the conversation again.

Inside the window, the assistant can answer normally.
Outside the window, an unsolicited free-form reply is rejected.
Templates must be approved before they can be used.
Design notifications as templates and conversations as replies.

What about voice notes, images, and files?

The channel carries text, images, and attachments, and voice notes render natively when the required audio tooling is available on the runtime.

Images and documents arrive as attachments the assistant can process.
Voice notes need audio tooling on the host to render as native notes.
Without it, audio still works but appears as a file attachment.
Test each media type you plan to rely on rather than assuming parity with chat apps.

Which setup mistakes waste the most time?

Pasting the display phone number where the phone number ID belongs, registering a webhook the runtime cannot answer, and testing only after the reply window has expired.

Number and number ID are different values and look similar in the dashboard.
A webhook that is not publicly reachable fails verification immediately.
Not subscribing to message events produces a silent, apparently broken bot.
Testing a day later hides the window rule until it bites in production.

Which primary sources support this page?

Product behavior is checked against the current deployment flow. These external links provide the upstream project or channel documentation used for setup details.

Direct answers

Frequently asked questions

Do I need a Facebook page to use the Cloud API?

A business portfolio and an app are required. Follow the current onboarding flow in the dashboard, which walks through what the specific app type needs.

Is the Cloud API free?

Meta charges for conversations under its own pricing model, and your model provider charges for tokens. Treat the two as separate line items.

Can I migrate from the QR bridge to the Cloud API later?

Plan for it from the start. The account, the number, and the integration are different, so treat the migration as a new channel rather than a switch.

Why is the webhook verification failing?

The endpoint is not reachable over HTTPS, or the verification token does not match. Fix reachability first, then recheck the token.

Key takeaways

There are two ways to put Hermes Agent on WhatsApp, and they are not equivalent. Meta's official WhatsApp Business Cloud API uses a business account and a dedicated number, needs no bridge process and carries no ban risk, but it requires a public webhook and follows Meta's messaging rules. The QR-based bridge is quicker for personal use and is the riskier of the two.
Start with one model, one channel, and one controlled test conversation.
Use managed hosting when deployment speed matters more than operating the server yourself.

Continue the setup

Blog guide

How to Deploy Hermes Agent on WhatsApp

Deploy Hermes Agent on WhatsApp with a managed runtime, guided QR connection, model selection, connection checks, recovery steps, and practical security guidance.

Read next

Blog guide