Getting started
Changelog
What changed in each wapi-cloud release. Upgrade with npm install wapi-cloud@latest.
npm install wapi-cloud@latest1.1.0
latest2026-10-13Possible 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)andmarkAsRead(id, { typingIndicator: true }). Docs - Business-scoped user IDs (BSUID): send to a BSUID with any send method and it is routed to
recipientautomatically. AddsSendMessageResult.userId, theisBsuid()helper, anduserId,parentUserId,username,profileNameandsenderon inbound messages and statuses. - Marketing Messages API:
messages.sendMarketingTemplate()(/marketing_messages) withproductPolicyandmessageActivitySharing. Docs - Calling API: new
whatsapp.callsmodule (connect,preAccept,accept,reject,terminate,getPermission,getSettings,updateSettings) andmessages.sendCallPermissionRequest(). - Groups API: new
whatsapp.groupsmodule (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).sendTemplateandsendReactioncan now reply to a message. - Webhooks: new
call,group_updateandunknown_fieldevents; parsedcontext,referral, interactive replies (button_reply,list_reply,nfm_reply),order,systemandunsupportedmessages; parsed statuspricing,conversationandbiz_opaque_callback_data; and anonListenerErrorhook. Docs sendFlow:flowAction: "data_exchange",flowTokenandmode.- 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_fieldinstead ofaccount_alert. handleExpresssends the 200 response before running listeners and isolates listener errors.handleExpressreturns 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-Afterdate values are handled and capped. - A 2xx response with a non-JSON body now returns an error.
client_secret,codeand tokens are redacted from URLs passed toonRequestandonResponse.media.downloadnow uses the configuredfetch, 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
verifySignaturereturnsfalsefor non-raw payloads instead of throwing. - Media messages without
linkormediaIdare rejected, andcaption/filenameare 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.