@dual-os/whatsapp-api
v7.1.0
Published
This plugin includes the existing API Actions and Workflow Triggers plus the whatsapp-api/direct Agent Channel. Existing action/trigger IDs, schemas and API authentication methods are unchanged. The additional Channel authentication is listed at plugin le
Readme
whatsapp-api: API and Agent Channel
This plugin includes the existing API Actions and Workflow Triggers plus the whatsapp-api/direct Agent Channel. Existing action/trigger IDs, schemas and API authentication methods are unchanged. The additional Channel authentication is listed at plugin level; per-action authentication subsets are intentionally deferred. Use existing API Connections for Actions/Triggers and the Channel credentials below for agent conversations. No migration of unused standalone Channel installations is provided.
Direct WhatsApp Channel
Direct Meta WhatsApp Cloud API Channel whatsapp-api/direct, Graph v25.0.
Supports 1:1 text in/out and inbound JPEG/PNG images up to 5 MiB. The Channel does not
support templates, groups, audio, edits, coexistence or history import.
The direct path requires Meta's telephone from identity. Username-only BSUID
items are ignored before acquisition; no contact/username identity is inferred. A message names
its sender by phone number (senderKey) and by the WhatsApp profile name the webhook lists for
that number; WhatsApp has no email.
Import whatsappApiPlugin from the package root or @dual-os/whatsapp-api/executable.
@dual-os/whatsapp-api/definition exports whatsappApiPluginBase.
Connection: access-token with accessToken, appId, appSecret, verifyToken.
Definition settings: {}. Deploy settings: businessAccountId, phoneNumberId,
explicit access (open/restricted), allowedSenderKeys (digits, restricted empty
denies all). Stable installation key is WABA/phone; operational state contains
checked asset/app identity and the installation ingress URL. Activation checks
existing assets and effective webhook routing, including number/WABA overrides,
the app's WABA subscription and its active messages subscription. An already
configured route completes activation without another GET challenge. Otherwise
it returns a checkpoint with ingress verification; the host persists it and
replays activate until remote setup is ready. Each replay registers what is
missing with the system user token, since Meta challenges the URL during the
call and the host answers only for a persisted checkpoint: it subscribes the app
to the WABA (POST /{waba}/subscribed_apps, only when unsubscribed, because that
call without a body clears a WABA override) and sets the number's
webhook_configuration.override_callback_uri to the ingress URL with the
Connection's verify token. The number override reaches no other number or WABA
of the app and outranks the WABA and app URLs; POST /{app}/subscriptions is
app-wide and Meta documents it as unsupported for WhatsApp. A refused
registration keeps the checkpoint for manual setup. The app's messages field
stays an App Dashboard setting. Remote read failures fail activation;
configuration checks do not guarantee continuous callback reachability.
Deactivation releases the host activation without deleting/unsubscribing assets
or removing the number override, which compatible versions share.
The host must enforce features.responseWindowMs using original received times
and provide deliver.responseToTimestamp. The adapter checks that time again
before POST. The exact SDK dependency is declared in package.json; it uses the
single operation-based Channel contract. HTTP acceptance stays pending; only verified delivered/read status
settles success. Opaque HMAC callback data binds Delivery, installation and
recipient; it is correlation, not idempotency. Transport uncertainty uses
unknown_completion. At-most-once hosts never blindly repeat an attempted send.
