hermes - 💡(How to fix) Fix [Bug]: WhatsApp Integration Failure

Bug Description

Issue Description

Attempting to send a message via WhatsApp using send_message consistently fails with internal errors.

Error Details

The WhatsApp integration appears to be broken. I have encountered two distinct errors when attempting to send a message to a valid phone number:

1. Connection Error: WhatsApp send failed: Cannot connect to host localhost:3000 ssl:default [Connect call failed ('127.0.0.1', 3000)]
2. Bridge Error: WhatsApp bridge error (500): {"error":"Cannot destructure property 'user' of 'jidDecode(...)' as it is undefined."}

Steps to Reproduce

Steps to Reproduce

1. Configure WhatsApp home channel (or attempt direct target).
2. Call send_message(message="...", target="whatsapp:<number>").
3. Receive 500 error from the WhatsApp bridge.

Expected Behavior

Expected Behavior

The message should be delivered successfully to the specified WhatsApp contact.

Actual Behavior

Actual Behavior

The integration fails with a 500 server error, specifically a jidDecode property destructuring error, indicating the bridge is failing to parse or validate the destination contact ID. Additionally, intermittent connection timeouts to the local gateway (port 3000) occur.

Affected Component

Gateway (Telegram/Discord/Slack/WhatsApp)

Messaging Platform (if gateway-related)

WhatsApp

Debug Report

Debug report uploaded:
  Report       https://paste.rs/Q95oM
  agent.log    https://paste.rs/8duJx
  gateway.log  https://paste.rs/gDPNR

Operating System

Linux (6.8.0-117-generic)

Python Version

No response

Hermes Version

No response

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

Root Cause Analysis

Error 1: jidDecode destructuring failure (500)

The send_message tool passes the recipient as an E.164-formatted phone number (e.g. +919427936052). The bridge's /send endpoint forwards this value directly to Baileys' sendMessage() without any transformation.

Baileys internally calls jidDecode() on the chatId to extract the JID components (user, server, device). jidDecode() expects a valid WhatsApp JID in the form <digits>@s.whatsapp.net (or @g.us for groups). When it receives a bare E.164 number like +919427936052 — which contains no @ domain part — the function returns undefined. The subsequent destructuring const { user } = jidDecode(...) then throws:

Cannot destructure property 'user' of 'jidDecode(...)' as it is undefined.

Root cause: No E.164 → WhatsApp JID normalization exists at the bridge's /send endpoint.

Error 2: Connection timeout to localhost:3000

The gateway cannot reach the bridge HTTP server on port 3000. This indicates the bridge Node.js process is either:

• Not running (crashed or never started), or
• Listening on a different port than the gateway expects.

This is a secondary issue — the 500 error above occurs when the bridge is running but rejects the malformed JID.

Proposed Fix (optional)

Proposed Fix

Fix 1: Add JID normalization in bridge.js

Add a normalizeOutgoingChatId() helper before the /send route and call it on the incoming chatId before passing it to Baileys:

// In scripts/whatsapp-bridge/bridge.js, before the app.post('/send', ...) handler:

function normalizeOutgoingChatId(id) {
  const s = String(id || '').trim();
  // Already a full JID (has @) — pass through unchanged
  if (s.includes('@')) return s;
  // Plain digits or E.164 (+countrycode...) → individual JID
  if (/^\+?\d+$/.test(s)) return s.replace(/^\+/, '') + '@s.whatsapp.net';
  return s;
}

Then in the /send handler, replace:

const sent = await sendWithTimeout(chatId, { text: chunks[i] });

with:

const resolvedChatId = normalizeOutgoingChatId(chatId);
const sent = await sendWithTimeout(resolvedChatId, { text: chunks[i] });

Fix 2: Ensure the bridge process is running

Restart the WhatsApp bridge and confirm it is listening on port 3000:

cd ~/.hermes/hermes-agent/scripts/whatsapp-bridge
node bridge.js &
# Verify:
curl http://localhost:3000/status

If the port conflicts with another process, update both bridge.js and the gateway config to use a free port consistently.

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR