<!-- BusyBot node reference — https://busybot.net/tools/whatsapp/ -->

> Node: WhatsApp Business Cloud (`whatsapp`) · Action (binary) · v1
> Category: Communication · Credentials: WhatsApp Business API (`whatsAppBusinessApi`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/whats-app-business-api/) 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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

Delete a media file:

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

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

```json
{
  "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.