WhatsApp Messaging Node
Send and manage WhatsApp messages, media, templates, groups, and commerce via the Meta WhatsApp Cloud API — directly from your BizFirstAI workflows.
What This Node Does
The WhatsApp node gives your workflows direct access to 57 operations across 8 resource groups. Send any message type supported by the WhatsApp Cloud API, manage media uploads and downloads, create and submit message templates, administer groups, manage phone numbers, generate QR codes, and drive Commerce catalog and order flows — all with credential-safe configuration through BizFirst Credentials Manager.
Authentication
| Field | Required | Description |
|---|---|---|
accessToken | Required | Permanent System User access token from Meta Business Manager. Never use a temporary user token. Store in BizFirst Credentials Manager and reference via {{ $credentials.whatsAppToken }}. |
phoneNumberId | Required | Numeric string ID of the WhatsApp Business phone number from Meta Business Manager (e.g. 123456789012345). Found in WhatsApp Manager under Phone Numbers. |
apiVersion | Optional | Meta Graph API version string, e.g. v18.0. Defaults to v18.0. Only override when targeting a specific API version. |
Key Concepts
24-Hour Customer Service Window
WhatsApp enforces a strict policy: you may only send free-form messages (text, image, video, audio, etc.) to a customer within 24 hours of their last inbound message. Outside this window, you must use an approved Template message. The node enforces this at the API level — Meta returns an error if you violate this rule.
Recipient Phone Number Format
The to field for all message send operations must be the recipient's international phone number without the leading + sign, e.g. 14155552671 for a US number. Include the full country code prefix.
Media Handling
For image, video, audio, document, and sticker messages you have two options:
- Link: Provide a publicly accessible HTTPS URL to the media file. Meta downloads it at send time. URL must remain accessible until delivery.
- Media ID: Pre-upload the file using
media/upload, then use the returnedmediaId. Faster for repeated sends and avoids URL expiry issues.
Template Messages
Template messages must be pre-approved by Meta before use. Create templates via template/create and submit for review with template/submitForReview. Once approved, use message/sendTemplate with the approved template name and language code to reach users outside the 24-hour window.
Operations at a Glance
Send a plain or link-preview text message.
Send an image by URL or pre-uploaded media ID with optional caption.
Send an MP4 or 3GPP video with optional caption.
Send an audio file by URL or media ID.
Send any document type with filename and caption.
Share GPS coordinates with optional name and address.
Send one or more vCard-style contact records.
Send button (up to 3) or list-picker interactive messages.
Send a Meta-approved template with dynamic variable components.
React to a specific message with an emoji.
Send a WebP sticker by pre-uploaded media ID.
Send a read receipt for an inbound message.
Delete a sent message (within 60 minutes).
Retrieve metadata for a single message by ID.
List messages with optional filters and pagination.
Upload a file to WhatsApp and receive a reusable media ID.
Retrieve metadata (URL, MIME type, size) for an uploaded media.
Download the binary content of an uploaded media file.
Delete a previously uploaded media object.
Create a new message template for Meta review.
Retrieve a single template by name and language.
List all templates with optional status filter.
Edit a template in REJECTED or PAUSED status.
Permanently delete a template by name.
Submit a DRAFT template to Meta for approval.
Retrieve the WhatsApp Business profile fields.
Update description, website, address, and email.
Get the current profile photo URL.
Upload and set a new profile photo.
Get details for a single registered phone number.
List all phone numbers on the WABA.
Update the display name for a registered number.
Request an OTP code to verify a phone number.
Submit OTP to complete phone number verification.
Register a verified phone number with the platform.
Deregister a number from the WhatsApp Business Platform.
Create a QR code that opens a chat with a pre-filled message.
Retrieve a single QR code by ID.
List all QR codes for the phone number.
Update the pre-filled message text on an existing QR code.
Delete a QR code by ID.
Create a new WhatsApp group with initial participants.
Get metadata for a group by group ID.
List groups the phone number is a member of.
Update the group name or description.
Delete a group (admin only).
List all participants in a group.
Add one or more participants to a group.
Remove a participant from a group.
Promote or demote a participant to/from admin.
Leave a group the phone number is a member of.
Generate an invite link for a group.
Retrieve the product catalog linked to the WABA.
Update catalog settings.
List products in the linked catalog.
Add a new product to the catalog.
Get details for a single product by ID.
Update product fields such as price and name.
Delete a product from the catalog.
List orders placed via WhatsApp Commerce.
Retrieve a single order by order ID.
Messaging Tier Limits
| Tier | Unique Recipients / 24 Hours |
|---|---|
| Tier 1 (default) | 1,000 |
| Tier 2 | 10,000 |
| Tier 3 | 100,000 |
| Unlimited | Unlimited (Meta approval required) |
Tiers upgrade automatically as message volume and quality ratings improve. Use phone-number/get to check your current limit. Always handle rate limit errors (HTTP 429, error code 131056) with exponential backoff.
Compliance Requirements
- Opt-in required: You must have documented evidence that users have opted in to receive WhatsApp messages from your business before sending anything. Sending without opt-in violates WhatsApp's Business Policy and can result in account suspension.
- Opt-out must be honoured: When a user requests not to be contacted, remove them from all lists immediately. Implement opt-out handling using a WebhookTrigger node to receive inbound messages.
- Template approval: All marketing, utility, and authentication templates must be approved by Meta before use. Rejected templates cannot be used to reach users.
- Quality rating: High block rates or spam reports lower your quality rating and can reduce your messaging tier or suspend your phone number.
Quick Start
- Create a Meta Business Manager account and set up a WhatsApp Business Account (WABA).
- Add your phone number in WhatsApp Manager and complete verification.
- Generate a permanent System User access token with
whatsapp_business_messagingpermission. - Copy your Phone Number ID from the WhatsApp Manager Phone Numbers page.
- Store the access token in BizFirst Credentials Manager.
- Add a WhatsApp node to your workflow, set
resourcetomessageandoperationtosendText. - Configure
accessToken,phoneNumberId,to, andtext. - Connect both the success and error output ports to downstream nodes.
- Test with your own verified number before deploying to production.