Hermes Agent WhatsApp Not Connecting: Fixes

The Bot Never Answers, and the Logs Are Quiet

You wired Hermes Agent to WhatsApp, the gateway starts without an error, and the number you messaged sits there like a rock. No incoming event in the logs, no delivery receipt on your phone, no obvious clue about which of the ten moving parts is broken. WhatsApp is the single most fragile channel in the Hermes stack, and almost every silent-connect case comes down to one of four causes.

Three of the four are silent by design, which is why the setup looks correct while nothing works. This post walks through each cause, how to confirm it is yours, and the exact fix. Start from the top - the order matters, because the first cause is the one that has been catching everyone since May 2026.

Cause 1: Your QR Code Library Was Broken by WhatsApp Shortcake

If you are running Hermes Agent through Baileys, WAHA, or any other WhatsApp Web-scraping library, and the QR code either refuses to scan or immediately logs the bot out again, you are hitting the Shortcake companion-linking rollout. WhatsApp now requires a WebAuthn passkey on the linked device, and a headless server does not have a passkey to present, so navigator.credentials.get() fails and the link is rejected with a 428.

Symptom: the QR renders, your phone scans it, and either the pair never completes or the session dies within a few minutes. Older sessions that used to auto-reconnect started returning Stream Errored (conflict) after May 2026 for the same reason. If it worked in April and stopped working overnight, this is your cause.

The fix has two shapes:

Move to the official Cloud API. This is the supported path, it is not vulnerable to Meta breaking a scraping library on a random Tuesday, and it is what the rest of this post assumes. Configure Hermes Agent with WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, and WHATSAPP_WEBHOOK_VERIFY_TOKEN instead of the QR flow. The WhatsApp deployment guide walks the full credential dance end to end.
Stay on Baileys if you have no other option, and pin the exact upstream commit that still works for you (the maintainers track passkey workarounds under issue #2672). Understand that the next Meta-side change breaks you again. This is the wrong choice for anything you actually rely on.

The rest of this post covers the Cloud API path.

Cause 2: Your WABA Is Not Subscribed to Your App

This is the single most common Cloud API failure and the most silent. You set the webhook URL in the App Dashboard, the verification GET succeeds, Meta shows a green tick next to the endpoint, and no message event ever arrives.

What is happening: setting the webhook URL on the app is only half the wiring. Each WhatsApp Business Account (WABA) also has to be subscribed to that app so its messages route to your endpoint. The App Dashboard does not show that subscription anywhere, and the webhook UI happily lets you finish setup with no WABA attached. Meta calls this the shadow delivery problem and the fix is one API call the setup wizard never mentions.

Check first:

curl -s "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

If the data array is empty, or does not contain your app's ID, this is your problem.

The fix:

curl -X POST "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

The call returns {"success": true} and the next incoming message flows to your Hermes Agent webhook within seconds. You do not need to restart the gateway. If you rotate the access token later, re-run this call: the subscription is tied to the app but the write requires a token with the whatsapp_business_management permission.

Cause 3: You Are Still Using the 24-Hour Temporary Token

The token Meta shows on the WhatsApp setup screen expires in exactly 24 hours. If you copied that into your Hermes Agent .env on Tuesday afternoon and the bot went silent on Wednesday afternoon, this is why.

Symptom: your gateway logs OAuthException or HTTP 401 on the next outbound send after the token expired. Incoming webhook calls from Meta can still land (they do not need your token) but every reply Hermes tries to post back fails, so the bot receives your message, generates a response, and drops it on the way out.

The fix is a permanent System User token, not a longer temporary one:

In Meta Business Suite open Users then System Users and create a new System User with the Admin role.
Assign your WhatsApp app and your WhatsApp Business Account to that System User with Full control.
Click Generate new token, pick your app, and tick both whatsapp_business_messaging (needed to send) and whatsapp_business_management (needed for the subscribed_apps call in Cause 2).
Set the expiry to Never. Copy the token, put it in WHATSAPP_ACCESS_TOKEN, restart the gateway.

Sanity-check it before you walk away:

curl -s "https://graph.facebook.com/v20.0/me?access_token=$WHATSAPP_ACCESS_TOKEN"

Should return your System User ID and name, not an OAuth error.

Cause 4: You Are Sending to the Wrong Phone Number ID

WhatsApp Cloud API uses three IDs and they are all easy to confuse: the phone number itself, the Phone Number ID, and the WABA ID. Hermes Agent needs the Phone Number ID, not the number. If you dropped the phone number into WHATSAPP_PHONE_NUMBER_ID, every outbound call returns Object with ID '+34...' does not exist and every incoming call succeeds but has no matching outbound path.

Confusingly, the Phone Number ID is a 15 or 16 digit number that looks a lot like a phone number. It is not one.

Where to find it: in the App Dashboard, open WhatsApp then API Setup. The From dropdown lists your registered numbers. Under each number, in small type, is a field labeled Phone number ID. That is the value Hermes Agent needs.

Verify the value you have is real:

curl -s "https://graph.facebook.com/v20.0/$WHATSAPP_PHONE_NUMBER_ID?access_token=$WHATSAPP_ACCESS_TOKEN"

A valid ID returns display_phone_number, verified_name, and quality_rating. A wrong ID returns a Graph API error whose message names the ID it could not find.

While you are here, check the WHATSAPP_BUSINESS_ACCOUNT_ID env var: it is a separate ID for the WABA that owns the number, used by the Cause 2 subscription call, and it is easy to swap the two when you copy them out of the dashboard.

Two Extra Traps Worth Ruling Out

If the four causes above are all clear and messages still do not flow, check these next:

The app is stuck in Dev mode. WhatsApp only ships webhooks for messages the app owner has sent or received in the last 24 hours, and only from numbers explicitly added under WhatsApp then API Setup then To. Switch the app to Live in App Review when you are ready for real user traffic.
The messages webhook field is not subscribed. In WhatsApp then Configuration, look at the Webhook fields section and confirm messages has a green tick. Meta lets you save a webhook URL with no fields subscribed, and it silently delivers nothing.

Diagnostic Order That Saves Time

When the bot goes silent, work through the causes in this order rather than reinstalling everything:

Are you on the QR path? If yes, migrate to Cloud API before spending another minute on anything else. Shortcake is not going away.
Is your WABA subscribed to your app? The one curl call above answers this in three seconds. Highest hit rate on Cloud API deployments.
Sanity-check the token. curl /me fails immediately if the token is dead, wrong, or missing scopes.
Verify the Phone Number ID. curl /$PHONE_NUMBER_ID returns the number's display fields when it is valid.
Check Dev mode and subscribed fields. Slower to inspect, less common as a root cause, but worth ruling out before you file a ticket with Meta.

For the full first-time WhatsApp install path, see the Hermes Agent WhatsApp deployment guide. If Telegram would fit your use case, the Telegram vs WhatsApp comparison covers the tradeoffs before you commit.

When You Would Rather Not Fight Meta Every Week

Meta ships webhook UI changes, tightens verification requirements, and breaks the QR code path on their own schedule. If your read is that a personal AI agent should not require a Business Manager account and a System User token to say hello back, get started with Hermify. Hermify runs a managed Hermes Agent on Telegram with the same memory and skills, live in about a minute, with none of the Meta configuration to babysit.