WhatsApp Platform

The adapter uses Meta's official WhatsApp Cloud API, receives signed webhooks through the shared OneBots HTTP host, and calls the versioned Graph API for outbound operations.

Coverage

• Private and Groups API messages with text, replies, images, video, audio, documents, stickers, locations, contacts, and reactions
• Native Template, Interactive, Flow, and future Cloud API message payloads
• Complete message-status projection with the original webhook change preserved
• Media upload, metadata lookup, authenticated download, and deletion
• Business profile, commerce, Flow lifecycle, phone registration, two-step verification, blocked users, and templates
• Conversational Automation welcome messages, prompts, and bot commands
• WABA webhook App subscription inspection, subscription, and removal
• WABA account details, controlled updates, and activity audit trails
• WABA phone-number inventory, filtering, sorting, pagination, and onboarding
• WABA schedules for business hours, automated responses, campaigns, and maintenance windows
• Groups API metadata and participants, settings, invite links, join approvals, and lifecycle/status webhooks
• Generic whatsapp_call for newly introduced Graph API resources
• await WhatsAppClient.ingest(rawEvent) for feeding an existing trusted connection into the same client, with deduplication committed only after all synchronous/asynchronous listeners succeed

Groups API is limited to eligible Official Business Accounts and groups created and managed by the current Phone Number through that API; it does not expose ordinary consumer groups. Cloud API also does not expose contact lists or arbitrary message history, so the adapter does not emulate those capabilities.

Configuration

whatsapp.my_bot:
  phone_number_id: "your_phone_number_id"
  business_account_id: "your_business_account_id"
  access_token: "your_long_lived_access_token"
  app_secret: "your_meta_app_secret"
  webhook_verify_token: "your_random_verify_token"
  api_version: "v23.0"

See the configuration reference for all fields.

Native payloads and APIs

Use a whatsapp_message segment for Template, Interactive, Flow, or any other native message payload. Platform actions expose business profile, commerce, and Flow lifecycle operations, while whatsapp_call accepts a safe relative Graph API resource:

await adapter.callAction("my_bot", "whatsapp_call", {
  method: "GET",
  resource: "your-waba-id/message_templates",
  query: { limit: 50 },
});

Absolute resource URLs are rejected so the access token cannot be sent to an unconfigured host. Permission-dependent actions declare either whatsapp_business_management or whatsapp_business_messaging in the capability manifest.

Fixed Groups actions cover create/get/list/update/delete, invite-link get/reset, join-request approval, participant removal, and message pin/unpin. Meta does not expose an endpoint for directly adding participants; invite users with an approved group-invite-link template instead. Subscribe the v23 fields group_lifecycle_update, group_participant_update, and group_settings_update in addition to messages when Groups API is enabled.

Message QR codes are available through client.qrCodes and the five fixed QR-code actions. Field selection uses an array, PNG/SVG image projection is explicit, and list queries support code filtering, a 1–25 limit, and cursor pagination. Requests and responses are validated against the Meta v23 shapes, including the single-item data array.

Message templates are managed through client.messageTemplates, with fixed actions for listing, lookup by ID, namespace discovery, creation, editing, and deletion by name or template ID. Top-level fields and responses are validated, while typed components retain Meta's evolving OTP, Flow, Catalog, MPM, and media-handle JSON fields through a safe serializable extension surface.

Flows are managed through client.flows instead of loose Graph payload forwarding. The module covers multipart creation and metadata updates, cross-WABA migration, controlled field projections, preview invalidation, endpoint metrics, Flow JSON upload and asset listing, plus publish, deprecate, and delete lifecycle transitions. Categories, fields, metric expressions, responses, and JSON serializability are validated at the seam.

Blocked users are managed through client.blockedUsers and the bulk block_users / unblock_users actions. Inputs are deduplicated E.164 arrays, mutation responses retain Meta's normalized wa_id mapping, and list pagination is structurally validated.

Media assets are managed through client.media and the four fixed media actions. Uploads enforce Meta's supported MIME types and size ceilings, while retrieval and deletion bind the media ID to the current phone_number_id. Temporary downloads only send the bearer token to trusted Meta hosts; metadata preserves the official string file_size, and deletion returns a validated structured result.

Conversational Automation is managed through client.automation. The fixed configuration action controls the welcome message, up to three prompts, and up to thirty uniquely named bot commands; empty arrays explicitly clear prompts or commands. Bot details are retrieved with a separate WABA Bot ID and a controlled field array, never by pretending that the Phone Number ID is the Bot ID.

WABA webhook App subscriptions are managed through client.webhookSubscriptions. Callers can inspect subscriptions, subscribe with the App default callback, provide a credential-free HTTPS override callback, or explicitly remove the current App subscription. Field projection always retains the App ID, while verify_token is write-only and never appears in structured responses.

WABA operations are managed through client.businessAccount and the get_business_account, update_business_account, and list_business_account_activities actions. Reads retain the account ID and name, writes are limited to the official name/timezone fields, and audit queries use controlled fields and enums with one-directional cursors, 1–100 item pages, and a maximum 90-day window. Audit results can contain actor IDs, IP addresses, and user agents and should be protected as security-audit data. Domain modules are the single typed client surface, avoiding duplicate forwarding APIs.

WABA phone-number assets are managed through client.businessPhoneNumbers and the list_business_phone_numbers / create_business_phone_number actions. Lists support controlled fields, equality filters for account mode, messaging tier and OBA status, official sort expressions, and cursor pagination. Creation validates the E.164 number without +, verified name, country calling code, migration flag, and BSP preverification ID. It starts Meta onboarding and returns the new number ID; it never switches the current client's phone_number_id.

WABA schedules are managed through client.schedules and the list_business_schedules / create_business_schedule actions. Fields, statuses, types, filters, sorts, HH:MM clocks, IANA time zones, unique weekdays, and recurrence values are validated at the seam, while shared Graph paging rejects non-HTTPS or credential-bearing links. Omitted timezone and activation values are sent explicitly as UTC / true, and official overnight ranges such as 18:00 → 08:00 remain valid. The WABA must have Schedule Management enabled.

Meta manages the Graph API lifecycle, so api_version must explicitly match a version enabled for the app.

References: WhatsApp Cloud API, Meta official Postman workspace.