WhatsApp Business Cloud

Send WhatsApp messages and manage media via the Business Cloud API

Overview

The WhatsApp Business Cloud tool uses the Graph API to send messages and manage media. Resources: (1) message — send text messages, media messages (image, video, audio, document, sticker) via link/media-ID/binary upload, contact cards, location messages, and template messages with dynamic components (body, header, button parameters); (2) media — upload binary data to WhatsApp, download media metadata/URL, and delete media. Media messages support three source modes: link (URL), mediaId (existing WhatsApp media), and binary upload (from workflow binary data). Template messages support body parameters (text, currency, date_time), button parameters (quick_reply, url), and header parameters (text, currency, date_time, image). Authentication uses Bearer token via WhatsApp Business API access token.

Category: Communication
Tool Name: whatsapp
Version: 1

Appearance: Icon: si-whatsapp | Color: #25D366

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires WhatsApp Business API credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
Message	message
Media	media

Operations

Operation	Value	Description
Send	send	Send a message (text, media, contact, or location)
Send Template	sendTemplate	Send a template message
Upload	upload	Upload media to WhatsApp
Download	download	Get media URL and metadata
Delete	delete	Delete media by ID

send and sendTemplate belong to the Message resource; upload, download and delete belong to Media.

Parameters

Message: Send

Parameter	Type	Required	Default	Description
Sender Phone Number ID	string	Yes	—	The ID of the phone number to send from. Find this in your WhatsApp Business dashboard under Phone Numbers. Supports expressions.
Recipient’s Phone Number	string	Yes	—	Phone number of the recipient (include country code, e.g., +1234567890). Special characters like -, (, ), + will be stripped automatically. Supports expressions.
Message Type	options	No	text	What kind of message to send. Each type reveals its own fields.
				Options: audio, contacts, document, image, location, sticker, text, video
Text Body	string	Yes	—	The body of the text message (max 4096 characters). Supports expressions. (shown when Message Type is text)
Additional Fields (additionalFieldsText)	collection	No	{}	Extra options for text messages. (shown when Message Type is text)
— Show URL Previews	boolean	No	false	Whether to display URL previews in text messages.
Media Source	options	No	useMediaLink	Where the media comes from. (shown when Message Type is audio, document, image, sticker, video)
				Options: useMediaLink (WhatsApp downloads the media from a URL), useMediaId (use an already-uploaded WhatsApp media ID), useMediaBinary (upload binary data from the current item)
Media Link	string	Yes	—	URL of the media file to send. Supports expressions. (shown when Message Type is audio, document, image, sticker, video and Media Source is useMediaLink)
Media ID (mediaId)	string	Yes	—	WhatsApp media ID of a previously uploaded file. Supports expressions. (shown when Message Type is audio, document, image, sticker, video and Media Source is useMediaId)
Binary Property	string	Yes	data	Name of the binary property containing the media file to upload and send. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use. (shown when Message Type is audio, document, image, sticker, video and Media Source is useMediaBinary)
Filename (mediaFilename)	string	Yes	—	The filename to display (required when using a media ID for documents). (shown when Message Type is document and Media Source is useMediaId)
Additional Fields (additionalFieldsMedia)	collection	No	{}	Extra options for media messages. (shown when Message Type is audio, document, image, sticker, video)
— Caption	string	No	—	Caption for the media (not supported for audio and sticker).
— Filename (filename)	string	No	—	Override filename for documents. (shown when Message Type is document)
Contact Name	fixedCollection	No	{}	The contact card’s name. (shown when Message Type is contacts)
— Formatted Name	string	Yes	—	Full formatted name of the contact.
— First Name	string	No	—	The contact’s given name.
— Last Name	string	No	—	The contact’s family name.
— Middle Name	string	No	—	The contact’s middle name.
— Prefix	string	No	—	Name prefix, e.g. Dr.
— Suffix	string	No	—	Name suffix, e.g. Jr.
Additional Contact Fields	collection	No	{}	Everything else on the contact card. (shown when Message Type is contacts)
— Addresses	fixedCollection	No	{}	One or more postal addresses.
— — Type	options	No	HOME	Which address this is.
				Options: HOME, WORK
— — Street	string	No	—	Street line of the address.
— — City	string	No	—	City of the address.
— — State	string	No	—	State or region of the address.
— — Zip	string	No	—	Postal code of the address.
— — Country	string	No	—	Country name.
— — Country Code	string	No	—	Country code for the address.
— Birthday	string	No	—	Contact birthday in YYYY-MM-DD format.
— Emails	fixedCollection	No	{}	One or more email addresses.
— — Type	options	No	HOME	Which email this is.
				Options: HOME, WORK
— — Email	string	No	—	The email address.
— Organization	fixedCollection	No	{}	Where the contact works.
— — Company	string	No	—	Company name.
— — Department	string	No	—	Department name.
— — Title	string	No	—	Job title.
— Phones	fixedCollection	No	{}	One or more phone numbers.
— — Type	options	No	CELL	Which phone this is.
				Options: CELL, HOME, IPHONE, MAIN, WORK
— — Phone	string	No	—	The phone number.
— — WhatsApp User ID	string	No	—	If omitted, the message will display an Invite to WhatsApp button.
— URLs	fixedCollection	No	{}	One or more web links.
— — Type	options	No	HOME	Which URL this is.
				Options: HOME, WORK
— — URL	string	No	—	The web address.
Longitude	number	Yes	0	Longitude of the location, between -180 and 180. (shown when Message Type is location)
Latitude	number	Yes	0	Latitude of the location, between -90 and 90. (shown when Message Type is location)
Additional Fields (additionalFieldsLocation)	collection	No	{}	Labels shown with the pin. (shown when Message Type is location)
— Name	string	No	—	Name of the location.
— Address	string	No	—	Address of the location.

Message: Send Template

Parameter	Type	Required	Default	Description
Sender Phone Number ID	string	Yes	—	The ID of the phone number to send from. Supports expressions.
Recipient’s Phone Number	string	Yes	—	Phone number of the recipient (include country code). Special characters like -, (, ), + will be stripped automatically. Supports expressions.
Template	string	Yes	—	Template name and language code, separated by ”|” (e.g., “hello_world|en_US”). Find available templates in your WhatsApp Business Manager. Supports expressions.
Components	fixedCollection	No	{}	Values for the template’s variable parts. Add one Component per template section.
— Type	options	No	body	Which part of the template this component fills.
				Options: body, button, header
— Parameters (bodyParameters)	fixedCollection	No	{}	Body variables, in template order. (shown when Type is body)
— — Type	options	No	text	Kind of body variable.
				Options: text, currency, date_time
— — Text	string	No	—	Literal text to substitute. (shown when Type is text)
— — Currency Code	string	No	—	ISO 4217 currency code (e.g., USD). (shown when Type is currency)
— — Amount	number	No	0	Amount value (will be multiplied by 1000 for the API). (shown when Type is currency)
— — Fallback Value	string	No	—	Text shown when the currency cannot be localised. (shown when Type is currency)
— — Date Time	string	No	—	Date/time string to use as the fallback value. (shown when Type is date_time)
— Sub Type	options	No	quick_reply	What the button does. (shown when Type is button)
				Options: quick_reply, url
— Index	number	No	0	Position of the button in the template, 0 to 2. (shown when Type is button)
— Parameters (buttonParameters)	fixedCollection	No	{}	The button’s value. (shown when Type is button)
— — Type	options	No	payload	Kind of button value.
				Options: payload, text
— — Payload	string	No	—	Payload returned to your webhook when the button is pressed. (shown when Type is payload)
— — Text	string	No	—	Text appended to the button’s URL. (shown when Type is text)
— Parameters (headerParameters)	fixedCollection	No	{}	Header variables. (shown when Type is header)
— — Type	options	No	text	Kind of header variable.
				Options: text, currency, date_time, image
— — Text	string	No	—	Literal text to substitute. (shown when Type is text)
— — Currency Code	string	No	—	ISO 4217 currency code. (shown when Type is currency)
— — Amount	number	No	0	Amount value (will be multiplied by 1000 for the API). (shown when Type is currency)
— — Date Time	string	No	—	Date/time string to use as the fallback value. (shown when Type is date_time)
— — Image Link	string	No	—	URL of the header image. (shown when Type is image)

Media: Upload

Parameter	Type	Required	Default	Description
Sender Phone Number ID	string	Yes	—	The ID of the phone number to associate with the uploaded media. Supports expressions.
Binary Property	string	Yes	data	Name of the binary property containing the file to upload. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use.
Additional Fields (additionalFieldsUpload)	collection	No	{}	Optional upload settings.
— Filename (mediaFileName)	string	No	—	Override the filename for the uploaded media.

Media: Download

Parameter	Type	Required	Default	Description
Media ID (mediaGetId)	string	Yes	—	The ID of the media to retrieve the URL for. Supports expressions.

Media: Delete

Parameter	Type	Required	Default	Description
Media ID (mediaDeleteId)	string	Yes	—	The ID of the media to delete. Supports expressions.

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

One output item per input item — no operation fans out. The WhatsApp Graph API response is merged onto the top level of the item JSON; anything already on the item passes through, and binary data is forwarded.

Operation	What lands on the item
send, sendTemplate	The send response, including the recipient entry and the created message’s ID
upload	The uploaded media’s id — feed it into a later Send as Media ID
download	The media metadata (including url and mime_type) and the file itself: the bytes are fetched from the returned URL and attached as the data binary property, named whatsapp_media_<mediaId>. Existing binary properties on the item are kept alongside it
delete	The delete acknowledgement; a 204 reply lands success: true

Recipient numbers are stripped to digits and must end up between 7 and 15 digits long; anything outside that range fails the item before the request is sent.

Usage Examples

• Send a text message via WhatsApp
• Send an image with caption via WhatsApp
• Upload a document and send it to a WhatsApp contact
• Send a template message with dynamic parameters
• Upload media to WhatsApp and get a media ID
• Get download URL for WhatsApp media
• Send a location message via WhatsApp

Example Configuration

Send a text message:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "message",
    "operation": "send",
    "phoneNumberId": "123456789012345",
    "recipientPhoneNumber": "+1234567890",
    "messageType": "text",
    "textBody": "Hello, this is a test message!",
    "additionalFieldsText": {
      "previewUrl": true
    }
  }
}

Send an image from a public URL:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "message",
    "operation": "send",
    "phoneNumberId": "123456789012345",
    "recipientPhoneNumber": "+1234567890",
    "messageType": "image",
    "mediaPath": "useMediaLink",
    "mediaLink": "https://example.com/image.jpg",
    "additionalFieldsMedia": {
      "caption": "Check out this image!"
    }
  }
}

Send a document by media ID:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "message",
    "operation": "send",
    "phoneNumberId": "123456789012345",
    "recipientPhoneNumber": "+1234567890",
    "messageType": "document",
    "mediaPath": "useMediaId",
    "mediaId": "1234567890",
    "mediaFilename": "report.pdf",
    "additionalFieldsMedia": {
      "caption": "Monthly report",
      "filename": "report.pdf"
    }
  }
}

Send a contact card:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "message",
    "operation": "send",
    "phoneNumberId": "123456789012345",
    "recipientPhoneNumber": "+1234567890",
    "messageType": "contacts",
    "contactName": {
      "data": {
        "formatted_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe"
      }
    },
    "additionalFieldsContact": {
      "phones": {
        "data": [
          { "type": "CELL", "phone": "+1234567890" }
        ]
      },
      "emails": {
        "data": [
          { "type": "WORK", "email": "john.doe@example.com" }
        ]
      }
    }
  }
}

Send a location:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "message",
    "operation": "send",
    "phoneNumberId": "123456789012345",
    "recipientPhoneNumber": "+1234567890",
    "messageType": "location",
    "longitude": -122.4194,
    "latitude": 37.7749,
    "additionalFieldsLocation": {
      "name": "San Francisco City Hall",
      "address": "1 Dr Carlton B Goodlett Pl, San Francisco, CA 94102"
    }
  }
}

Send a template message with one body variable:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "message",
    "operation": "sendTemplate",
    "phoneNumberId": "123456789012345",
    "recipientPhoneNumber": "+1234567890",
    "template": "hello_world|en_US",
    "components": {
      "component": [
        {
          "type": "body",
          "bodyParameters": {
            "parameter": [
              { "type": "text", "text": "John" }
            ]
          }
        }
      ]
    }
  }
}

Send a template with header, body and button components:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "message",
    "operation": "sendTemplate",
    "phoneNumberId": "123456789012345",
    "recipientPhoneNumber": "+1234567890",
    "template": "order_confirmation|en_US",
    "components": {
      "component": [
        {
          "type": "header",
          "headerParameters": {
            "parameter": [
              { "type": "text", "text": "Order #12345" }
            ]
          }
        },
        {
          "type": "body",
          "bodyParameters": {
            "parameter": [
              { "type": "text", "text": "John" },
              { "type": "text", "text": "$29.99" }
            ]
          }
        },
        {
          "type": "button",
          "sub_type": "quick_reply",
          "index": 0,
          "buttonParameters": {
            "parameter": { "type": "payload", "payload": "view_order_12345" }
          }
        }
      ]
    }
  }
}

Upload a file from an upstream node:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "media",
    "operation": "upload",
    "phoneNumberId": "123456789012345",
    "binaryPropertyName": "data",
    "additionalFieldsUpload": {
      "mediaFileName": "image.jpg"
    }
  }
}

Send the file you just uploaded, using the media ID from the previous node’s output:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "message",
    "operation": "send",
    "phoneNumberId": "123456789012345",
    "recipientPhoneNumber": "+1234567890",
    "messageType": "document",
    "mediaPath": "useMediaId",
    "mediaId": "{{ $json.id }}",
    "mediaFilename": "document.pdf"
  }
}

Fetch a media file’s URL and bytes:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "media",
    "operation": "download",
    "mediaGetId": "1234567890"
  }
}

Delete a media file:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "media",
    "operation": "delete",
    "mediaDeleteId": "1234567890"
  }
}

Send an image straight from an upstream node’s binary data:

{
  "type": "whatsapp",
  "parameters": {
    "resource": "message",
    "operation": "send",
    "phoneNumberId": "123456789012345",
    "recipientPhoneNumber": "+1234567890",
    "messageType": "image",
    "mediaPath": "useMediaBinary",
    "binaryPropertyName": "imageData",
    "additionalFieldsMedia": {
      "caption": "Uploaded image"
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Send WhatsApp messages (text, media, contacts, location, templates) and manage media via the WhatsApp Business Cloud API.

Media Workflow Pattern

A common pattern is to upload media first, then use the returned media ID to send messages:

1. Upload media with Resource media / Operation upload and the binary property holding the file.
2. Send the message with Media Source useMediaId and Media ID set to {{ $json.id }} from the upload step.

Choosing useMediaBinary instead does both in one node — the file is uploaded and sent in the same run — at the cost of re-uploading it on every send.

Sending Failures

A first message to a brand-new test number often fails until you have messaged that number from the Meta developer portal at least once; the node surfaces that case with an explicit hint.