[BUG] Cloud API (WHATSAPP-BUSINESS) status webhooks crash messageHandle (TypeError reading 'name') on released versions — fixed in develop (#2514), please release

[crottolo]

Summary

On released versions (v2.3.7, the current evoapicloud/evolution-api:latest, and v2.4.0-rc2), incoming status webhooks for the WHATSAPP-BUSINESS (Cloud API) integration crash messageHandle(), so MESSAGES_UPDATE is never emitted. As a result, outbound message delivery/read receipts never update — messages stay PENDING and the double check never appears.

The bug is already fixed in develop by #2514 (commit 6d696f3), but that fix is not in any release yet. This issue documents the root cause for affected users and requests a release that includes #2514.

Affected versions

Version	Affected
v2.3.7	✅ yes
evoapicloud/evolution-api:latest (currently 2.3.7)	✅ yes
v2.4.0-rc2	✅ yes
develop	❌ no (fixed by #2514)

Root cause

src/api/integrations/channel/meta/whatsapp.business.service.ts → messageHandle():

if (received.contacts) pushName = received.contacts[0].profile.name;

WhatsApp Cloud API status webhooks include a contacts array whose entry has wa_id / user_id but no profile object:

{
  "messaging_product": "whatsapp",
  "metadata": { "phone_number_id": "..." },
  "contacts": [{ "wa_id": "39XXXXXXXXXX", "user_id": "IT.xxxxxxxx" }],
  "statuses": [{ "id": "wamid....", "status": "sent", "recipient_id": "39XXXXXXXXXX" }]
}

So received.contacts[0].profile is undefined and .name throws. This line runs at the top of messageHandle() (inside the single try), before the if (received.statuses) { ... } block, so the exception aborts the handler and Events.MESSAGES_UPDATE is never sent.

Log

LOG   [ChannelStartupService]  Contenido recibido en eventHandler:
{
  "messaging_product": "whatsapp",
  "metadata": { "phone_number_id": "..." },
  "contacts": [{ "wa_id": "39XXXXXXXXXX", "user_id": "IT.xxxxxxxx" }],
  "statuses": [{ "id": "wamid....", "status": "delivered", "recipient_id": "39XXXXXXXXXX" }]
}
ERROR [ChannelStartupService]  TypeError: Cannot read properties of undefined (reading 'name')
    at messageHandle (.../channel/meta/whatsapp.business.service.ts)
    at eventHandler

Steps to reproduce

1. WHATSAPP-BUSINESS (Cloud API) instance on a released version, webhook subscribed to MESSAGES_UPDATE.
2. Send an outbound message; the recipient receives it.
3. Meta posts a statuses webhook → server logs the TypeError above; no MESSAGES_UPDATE reaches the configured webhook; the message status stays PENDING.

Fix (already in develop, #2514)

const incomingContact = received?.contacts?.[0];
pushName = incomingContact?.profile?.name ?? incomingContact?.name ?? incomingContact?.wa_id ?? undefined;

Verified: applying this guard (building from develop / backporting #2514 onto 2.3.7) resolves the crash — statuses are processed, MESSAGES_UPDATE is emitted, and delivery/read receipts (single → double → blue check) work correctly for the Cloud API integration.

Request

Please cut a patch release (e.g. 2.3.8) or expedite 2.4.0 stable including #2514, since all WHATSAPP-BUSINESS users on released images currently lose delivery/read receipts.

Related: #2514 (fix), #2486 (MESSAGES_UPDATE Business API).

Thanks for the project! 🙏