Getting started

Changelog

What changed in each wapi-cloud release. Upgrade with npm install wapi-cloud@latest.

npm install wapi-cloud@latest

1.1.0

latest2026-10-13
Possible breaking change for TypeScript users: from on inbound messages and recipientId on statuses are now optional, because users with usernames may not expose a phone number. Use msg.sender to reply.

Added

  • Typing indicator: messages.showTyping(id) and markAsRead(id, { typingIndicator: true }). Docs
  • Business-scoped user IDs (BSUID): send to a BSUID with any send method and it is routed to recipient automatically. Adds SendMessageResult.userId, the isBsuid() helper, and userId, parentUserId, username, profileName and sender on inbound messages and statuses.
  • Marketing Messages API: messages.sendMarketingTemplate() (/marketing_messages) with productPolicy and messageActivitySharing. Docs
  • Calling API: new whatsapp.calls module (connect, preAccept, accept, reject, terminate, getPermission, getSettings, updateSettings) and messages.sendCallPermissionRequest().
  • Groups API: new whatsapp.groups module (create, list, get, update, delete, invite links, join requests, remove participants). Send to a group with { recipientType: "group" }.
  • Send options: every send method accepts SendOptions (recipientType, bizOpaqueCallbackData, replyToMessageId, phoneNumberId). sendTemplate and sendReaction can now reply to a message.
  • Webhooks: new call, group_update and unknown_field events; parsed context, referral, interactive replies (button_reply, list_reply, nfm_reply), order, system and unsupported messages; parsed status pricing, conversation and biz_opaque_callback_data; and an onListenerError hook. Docs
  • sendFlow: flowAction: "data_exchange", flowToken and mode.
  • Test suite (npm test) and opt-in live tests (npm run test:live).

Changed

  • Default Graph API version is now v25.0.
  • Unrecognised webhook fields are emitted as unknown_field instead of account_alert.
  • handleExpress sends the 200 response before running listeners and isolates listener errors.
  • handleExpress returns 400 with a log message if the body is not raw.

Fixed

  • POST requests are no longer retried after timeouts, network errors or 5xx responses, which could send duplicate messages. Opt in with retryUnsafe.
  • Meta rate-limit error codes are retried even when returned as HTTP 400 or 403.
  • The timeout now covers reading the response body, and Retry-After date values are handled and capped.
  • A 2xx response with a non-JSON body now returns an error.
  • client_secret, code and tokens are redacted from URLs passed to onRequest and onResponse.
  • media.download now uses the configured fetch, timeout and hooks.
  • Corrected the error-code hints (190, 131005, 131021, 131045, 132005, 132007, 133005 and others).
  • The webhook verify-token check is timing-safe, and verifySignature returns false for non-raw payloads instead of throwing.
  • Media messages without link or mediaId are rejected, and caption/filename are sent only where the API accepts them.
  • README webhook example no longer passes a Buffer to parse.

Migrating from 1.0.x

// Before
await whatsapp.messages.sendText(msg.from, { body: "Hi" });

// After: from may be undefined for username users
await whatsapp.messages.sendText(msg.sender, { body: "Hi" });

1.0.1

2026-08-22
  • Maintenance release.

1.0.0

initial release2026-08-21
  • Typed { data, error } client for the WhatsApp Cloud API: messages, templates, media, contacts, phone numbers, business profile, two-step verification, catalogs, products, commerce settings, flows, QR codes, analytics and embedded signup.
  • Webhook helpers: signature verification, event parsing and an Express one-liner.
  • Auto-pagination with for await.