# WhatsApp (/integrations/whatsapp)





{/* MANUAL-CONTENT-START:intro */}

Use [WhatsApp](https://www.whatsapp.com/) Cloud API to send text, template, media, or interactive messages, react to messages, and manage media. Message webhooks can start workflows. See the messaging-window requirement below before choosing between a free-form message and a template.

{/* MANUAL-CONTENT-END */}

## Use the block [#usage-instructions]

Send text, template, media, and interactive messages, react to messages, and mark messages as read through the WhatsApp Cloud API. Free-form messages only reach a recipient within 24 hours of their last message to you — outside that window WhatsApp requires a pre-approved template.

## Actions [#actions]

### WhatsApp Send Message [#whatsapp-send-message]

Send a free-form text message through the WhatsApp Cloud API. Only works inside the 24-hour customer service window — use Send Template to start a conversation.

<ReferenceDetails>
  #### Input [#input]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `phoneNumber` | string | Yes | Recipient phone number with country code (e.g., +14155552671) |
  | `message` | string | Yes | Plain text message content to send (max 4096 characters) |
  | `phoneNumberId` | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |
  | `previewUrl` | boolean | No | Whether WhatsApp should try to render a link preview for the first URL in the message |

  #### Output [#output]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Send success status |
  | `messageId` | string | WhatsApp message identifier |
  | `messageStatus` | string | Pacing status from the send API: accepted, held\_for\_quality\_assessment, or paused. Acceptance is not delivery — use the webhook trigger for delivery status. |
  | `messagingProduct` | string | Messaging product returned by the send API |
  | `inputPhoneNumber` | string | Recipient phone number echoed by the send API |
  | `whatsappUserId` | string | Resolved WhatsApp user ID for the recipient |
  | `contacts` | array | Recipient contacts returned by the send API (each item includes input and wa\_id) |
  | `mediaId` | string | Media asset ID from Upload Media, or the ID downloaded by Download Media |
  | `file` | file | Media downloaded by Download Media, stored as a workflow file |
  | `fileName` | string | Name of the file uploaded by Upload Media |
  | `mimeType` | string | MIME type of the uploaded or downloaded media |
  | `size` | number | Size in bytes of the file uploaded by Upload Media |
  | `fileSize` | number | Size in bytes of the downloaded media |
  | `sha256` | string | SHA-256 hash WhatsApp reported for the downloaded media |
  | `eventType` | string | Webhook classification such as incoming\_message, message\_status, or mixed |
  | `from` | string | Sender phone number from the first incoming message |
  | `recipientId` | string | Recipient phone number from the first status update in the batch |
  | `phoneNumberId` | string | Business phone number ID from the first message or status item in the batch |
  | `displayPhoneNumber` | string | Business display phone number from the first message or status item in the batch |
  | `text` | string | Text body from the first incoming text message |
  | `timestamp` | string | Timestamp from the first message or status item in the batch |
  | `messageType` | string | Type of the first incoming message in the batch, such as text, image, or system |
  | `mediaMimeType` | string | MIME type of the first incoming media message in the webhook batch |
  | `caption` | string | Caption on the first incoming image, video, or document message |
  | `status` | string | First outgoing message status in the batch, such as sent, delivered, or read |
  | `contact` | json | First sender contact in the webhook batch (wa\_id, profile.name) |
  | `messages` | json | All incoming message objects from the webhook batch, flattened across entries/changes |
  | `statuses` | json | All message status objects from the webhook batch, flattened across entries/changes |
  | `webhookContacts` | json | All sender contact profiles from the webhook batch |
  | `conversation` | json | Conversation metadata from the first status update in the batch (id, expiration\_timestamp, origin.type) |
  | `pricing` | json | Pricing metadata from the first status update in the batch (billable, pricing\_model, category) |
  | `raw` | json | Full structured WhatsApp webhook payload |
  | `error` | string | Error information if sending fails |
</ReferenceDetails>

### WhatsApp Send Template [#whatsapp-send-template]

Send a pre-approved WhatsApp template message. Required to start a conversation or to message a user outside the 24-hour customer service window.

<ReferenceDetails>
  #### Input [#input-1]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `phoneNumber` | string | Yes | Recipient phone number with country code (e.g., +14155552671) |
  | `templateName` | string | Yes | Name of the approved message template |
  | `languageCode` | string | Yes | Template language/locale code (e.g., en\_US) |
  | `components` | json | No | Template components array with parameters for header/body/button variables, per the WhatsApp template message schema |
  | `phoneNumberId` | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |

  #### Output [#output-1]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Send success status |
  | `messageId` | string | WhatsApp message identifier |
  | `messageStatus` | string | Pacing status from the send API: accepted, held\_for\_quality\_assessment, or paused. Acceptance is not delivery — use the webhook trigger for delivery status. |
  | `messagingProduct` | string | Messaging product returned by the send API |
  | `inputPhoneNumber` | string | Recipient phone number echoed by the send API |
  | `whatsappUserId` | string | Resolved WhatsApp user ID for the recipient |
  | `contacts` | array | Recipient contacts returned by the send API (each item includes input and wa\_id) |
  | `mediaId` | string | Media asset ID from Upload Media, or the ID downloaded by Download Media |
  | `file` | file | Media downloaded by Download Media, stored as a workflow file |
  | `fileName` | string | Name of the file uploaded by Upload Media |
  | `mimeType` | string | MIME type of the uploaded or downloaded media |
  | `size` | number | Size in bytes of the file uploaded by Upload Media |
  | `fileSize` | number | Size in bytes of the downloaded media |
  | `sha256` | string | SHA-256 hash WhatsApp reported for the downloaded media |
  | `eventType` | string | Webhook classification such as incoming\_message, message\_status, or mixed |
  | `from` | string | Sender phone number from the first incoming message |
  | `recipientId` | string | Recipient phone number from the first status update in the batch |
  | `phoneNumberId` | string | Business phone number ID from the first message or status item in the batch |
  | `displayPhoneNumber` | string | Business display phone number from the first message or status item in the batch |
  | `text` | string | Text body from the first incoming text message |
  | `timestamp` | string | Timestamp from the first message or status item in the batch |
  | `messageType` | string | Type of the first incoming message in the batch, such as text, image, or system |
  | `mediaMimeType` | string | MIME type of the first incoming media message in the webhook batch |
  | `caption` | string | Caption on the first incoming image, video, or document message |
  | `status` | string | First outgoing message status in the batch, such as sent, delivered, or read |
  | `contact` | json | First sender contact in the webhook batch (wa\_id, profile.name) |
  | `messages` | json | All incoming message objects from the webhook batch, flattened across entries/changes |
  | `statuses` | json | All message status objects from the webhook batch, flattened across entries/changes |
  | `webhookContacts` | json | All sender contact profiles from the webhook batch |
  | `conversation` | json | Conversation metadata from the first status update in the batch (id, expiration\_timestamp, origin.type) |
  | `pricing` | json | Pricing metadata from the first status update in the batch (billable, pricing\_model, category) |
  | `raw` | json | Full structured WhatsApp webhook payload |
  | `error` | string | Error information if sending fails |
</ReferenceDetails>

### WhatsApp Send Media [#whatsapp-send-media]

Send an image, document, video, audio, or sticker message. Accepts an uploaded file, a media ID, or a public link.

<ReferenceDetails>
  #### Input [#input-2]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `phoneNumber` | string | Yes | Recipient phone number with country code (e.g., +14155552671) |
  | `mediaType` | string | Yes | Type of media to send: image, document, video, audio, or sticker |
  | `file` | file | No | File to send. Uploaded to WhatsApp first, then sent. Use Upload Media instead when sending the same file repeatedly. |
  | `mediaId` | string | No | ID of media previously uploaded to WhatsApp. Alternative to file or mediaLink. |
  | `mediaLink` | string | No | Public HTTPS URL of the media. Alternative to file or mediaId. |
  | `caption` | string | No | Optional caption for image, video, or document media (max 1024 characters). Ignored for audio and sticker. |
  | `filename` | string | No | Optional file name shown to the recipient for document media |
  | `phoneNumberId` | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |

  #### Output [#output-2]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Send success status |
  | `messageId` | string | WhatsApp message identifier |
  | `messageStatus` | string | Pacing status from the send API: accepted, held\_for\_quality\_assessment, or paused. Acceptance is not delivery — use the webhook trigger for delivery status. |
  | `messagingProduct` | string | Messaging product returned by the send API |
  | `inputPhoneNumber` | string | Recipient phone number echoed by the send API |
  | `whatsappUserId` | string | Resolved WhatsApp user ID for the recipient |
  | `contacts` | array | Recipient contacts returned by the send API (each item includes input and wa\_id) |
  | `mediaId` | string | Media asset ID from Upload Media, or the ID downloaded by Download Media |
  | `file` | file | Media downloaded by Download Media, stored as a workflow file |
  | `fileName` | string | Name of the file uploaded by Upload Media |
  | `mimeType` | string | MIME type of the uploaded or downloaded media |
  | `size` | number | Size in bytes of the file uploaded by Upload Media |
  | `fileSize` | number | Size in bytes of the downloaded media |
  | `sha256` | string | SHA-256 hash WhatsApp reported for the downloaded media |
  | `eventType` | string | Webhook classification such as incoming\_message, message\_status, or mixed |
  | `from` | string | Sender phone number from the first incoming message |
  | `recipientId` | string | Recipient phone number from the first status update in the batch |
  | `phoneNumberId` | string | Business phone number ID from the first message or status item in the batch |
  | `displayPhoneNumber` | string | Business display phone number from the first message or status item in the batch |
  | `text` | string | Text body from the first incoming text message |
  | `timestamp` | string | Timestamp from the first message or status item in the batch |
  | `messageType` | string | Type of the first incoming message in the batch, such as text, image, or system |
  | `mediaMimeType` | string | MIME type of the first incoming media message in the webhook batch |
  | `caption` | string | Caption on the first incoming image, video, or document message |
  | `status` | string | First outgoing message status in the batch, such as sent, delivered, or read |
  | `contact` | json | First sender contact in the webhook batch (wa\_id, profile.name) |
  | `messages` | json | All incoming message objects from the webhook batch, flattened across entries/changes |
  | `statuses` | json | All message status objects from the webhook batch, flattened across entries/changes |
  | `webhookContacts` | json | All sender contact profiles from the webhook batch |
  | `conversation` | json | Conversation metadata from the first status update in the batch (id, expiration\_timestamp, origin.type) |
  | `pricing` | json | Pricing metadata from the first status update in the batch (billable, pricing\_model, category) |
  | `raw` | json | Full structured WhatsApp webhook payload |
  | `error` | string | Error information if sending fails |
</ReferenceDetails>

### WhatsApp Send Interactive [#whatsapp-send-interactive]

Send an interactive WhatsApp message with reply buttons or a selectable list.

<ReferenceDetails>
  #### Input [#input-3]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `phoneNumber` | string | Yes | Recipient phone number with country code (e.g., +14155552671) |
  | `bodyText` | string | Yes | Main body text of the interactive message (max 1024 characters with buttons, 4096 with a list) |
  | `headerText` | string | No | Optional plain-text header shown above the body (max 60 characters) |
  | `footerText` | string | No | Optional footer text shown below the body (max 60 characters) |
  | `buttons` | json | No | Reply buttons array (max 3), each item: \{ "type": "reply", "reply": \{ "id": "...", "title": "..." } }. Button title max 20 characters, id max 256. Provide buttons or sections. |
  | `listButtonText` | string | No | Label for the menu button that opens the list, max 20 characters (required when sending a list) |
  | `sections` | json | No | List sections array (max 10 sections, 10 rows total), each item: \{ "title": "...", "rows": \[\{ "id": "...", "title": "...", "description": "..." }] }. Section and row titles max 24 characters, row description max 72. Provide sections or buttons. |
  | `phoneNumberId` | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |

  #### Output [#output-3]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Send success status |
  | `messageId` | string | WhatsApp message identifier |
  | `messageStatus` | string | Pacing status from the send API: accepted, held\_for\_quality\_assessment, or paused. Acceptance is not delivery — use the webhook trigger for delivery status. |
  | `messagingProduct` | string | Messaging product returned by the send API |
  | `inputPhoneNumber` | string | Recipient phone number echoed by the send API |
  | `whatsappUserId` | string | Resolved WhatsApp user ID for the recipient |
  | `contacts` | array | Recipient contacts returned by the send API (each item includes input and wa\_id) |
  | `mediaId` | string | Media asset ID from Upload Media, or the ID downloaded by Download Media |
  | `file` | file | Media downloaded by Download Media, stored as a workflow file |
  | `fileName` | string | Name of the file uploaded by Upload Media |
  | `mimeType` | string | MIME type of the uploaded or downloaded media |
  | `size` | number | Size in bytes of the file uploaded by Upload Media |
  | `fileSize` | number | Size in bytes of the downloaded media |
  | `sha256` | string | SHA-256 hash WhatsApp reported for the downloaded media |
  | `eventType` | string | Webhook classification such as incoming\_message, message\_status, or mixed |
  | `from` | string | Sender phone number from the first incoming message |
  | `recipientId` | string | Recipient phone number from the first status update in the batch |
  | `phoneNumberId` | string | Business phone number ID from the first message or status item in the batch |
  | `displayPhoneNumber` | string | Business display phone number from the first message or status item in the batch |
  | `text` | string | Text body from the first incoming text message |
  | `timestamp` | string | Timestamp from the first message or status item in the batch |
  | `messageType` | string | Type of the first incoming message in the batch, such as text, image, or system |
  | `mediaMimeType` | string | MIME type of the first incoming media message in the webhook batch |
  | `caption` | string | Caption on the first incoming image, video, or document message |
  | `status` | string | First outgoing message status in the batch, such as sent, delivered, or read |
  | `contact` | json | First sender contact in the webhook batch (wa\_id, profile.name) |
  | `messages` | json | All incoming message objects from the webhook batch, flattened across entries/changes |
  | `statuses` | json | All message status objects from the webhook batch, flattened across entries/changes |
  | `webhookContacts` | json | All sender contact profiles from the webhook batch |
  | `conversation` | json | Conversation metadata from the first status update in the batch (id, expiration\_timestamp, origin.type) |
  | `pricing` | json | Pricing metadata from the first status update in the batch (billable, pricing\_model, category) |
  | `raw` | json | Full structured WhatsApp webhook payload |
  | `error` | string | Error information if sending fails |
</ReferenceDetails>

### WhatsApp Send Reaction [#whatsapp-send-reaction]

React to a WhatsApp message with an emoji. Send an empty emoji to remove an existing reaction.

<ReferenceDetails>
  #### Input [#input-4]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `phoneNumber` | string | Yes | Recipient phone number with country code (e.g., +14155552671) |
  | `messageId` | string | Yes | ID (wamid) of the message to react to. Not delivered if the message is over 30 days old, deleted, not in this chat thread, or itself a reaction. |
  | `emoji` | string | No | Emoji to react with. Leave empty to remove an existing reaction. |
  | `phoneNumberId` | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |

  #### Output [#output-4]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Send success status |
  | `messageId` | string | WhatsApp message identifier |
  | `messageStatus` | string | Pacing status from the send API: accepted, held\_for\_quality\_assessment, or paused. Acceptance is not delivery — use the webhook trigger for delivery status. |
  | `messagingProduct` | string | Messaging product returned by the send API |
  | `inputPhoneNumber` | string | Recipient phone number echoed by the send API |
  | `whatsappUserId` | string | Resolved WhatsApp user ID for the recipient |
  | `contacts` | array | Recipient contacts returned by the send API (each item includes input and wa\_id) |
  | `mediaId` | string | Media asset ID from Upload Media, or the ID downloaded by Download Media |
  | `file` | file | Media downloaded by Download Media, stored as a workflow file |
  | `fileName` | string | Name of the file uploaded by Upload Media |
  | `mimeType` | string | MIME type of the uploaded or downloaded media |
  | `size` | number | Size in bytes of the file uploaded by Upload Media |
  | `fileSize` | number | Size in bytes of the downloaded media |
  | `sha256` | string | SHA-256 hash WhatsApp reported for the downloaded media |
  | `eventType` | string | Webhook classification such as incoming\_message, message\_status, or mixed |
  | `from` | string | Sender phone number from the first incoming message |
  | `recipientId` | string | Recipient phone number from the first status update in the batch |
  | `phoneNumberId` | string | Business phone number ID from the first message or status item in the batch |
  | `displayPhoneNumber` | string | Business display phone number from the first message or status item in the batch |
  | `text` | string | Text body from the first incoming text message |
  | `timestamp` | string | Timestamp from the first message or status item in the batch |
  | `messageType` | string | Type of the first incoming message in the batch, such as text, image, or system |
  | `mediaMimeType` | string | MIME type of the first incoming media message in the webhook batch |
  | `caption` | string | Caption on the first incoming image, video, or document message |
  | `status` | string | First outgoing message status in the batch, such as sent, delivered, or read |
  | `contact` | json | First sender contact in the webhook batch (wa\_id, profile.name) |
  | `messages` | json | All incoming message objects from the webhook batch, flattened across entries/changes |
  | `statuses` | json | All message status objects from the webhook batch, flattened across entries/changes |
  | `webhookContacts` | json | All sender contact profiles from the webhook batch |
  | `conversation` | json | Conversation metadata from the first status update in the batch (id, expiration\_timestamp, origin.type) |
  | `pricing` | json | Pricing metadata from the first status update in the batch (billable, pricing\_model, category) |
  | `raw` | json | Full structured WhatsApp webhook payload |
  | `error` | string | Error information if sending fails |
</ReferenceDetails>

### WhatsApp Mark As Read [#whatsapp-mark-as-read]

Mark a received WhatsApp message as read so the sender sees blue checkmarks, optionally showing a typing indicator.

<ReferenceDetails>
  #### Input [#input-5]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `messageId` | string | Yes | ID (wamid) of the incoming message to mark as read |
  | `showTypingIndicator` | boolean | No | Show a typing indicator to the sender while a reply is composed. Dismissed once you respond or after 25 seconds, whichever comes first. |
  | `phoneNumberId` | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |

  #### Output [#output-5]

  | Parameter | Type | Description |
  | - | - | - |
  | `success` | boolean | Whether the message was successfully marked as read |
</ReferenceDetails>

### WhatsApp Upload Media [#whatsapp-upload-media]

Upload a file to WhatsApp and get a media ID for sending. Uploaded media is retained for 30 days and can back many sends.

<ReferenceDetails>
  #### Input [#input-6]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `file` | file | Yes | File to upload. WhatsApp limits: images 5 MB, video and audio 16 MB, documents 100 MB, stickers 500 KB. |
  | `phoneNumberId` | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |

  #### Output [#output-6]

  | Parameter | Type | Description |
  | - | - | - |
  | `mediaId` | string | WhatsApp media ID. Pass this to Send Media to attach the uploaded file. |
  | `fileName` | string | Name of the uploaded file |
  | `mimeType` | string | MIME type WhatsApp received the file as |
  | `size` | number | Size of the uploaded file in bytes |
</ReferenceDetails>

### WhatsApp Download Media [#whatsapp-download-media]

Download media a customer sent you. Takes the media ID from an incoming WhatsApp message and stores the file in the workflow.

<ReferenceDetails>
  #### Input [#input-7]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `mediaId` | string | Yes | Media asset ID from an incoming message, e.g. \<whatsapp.messages\[0].mediaId>. This is not the message ID (wamid). |
  | `phoneNumberId` | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |

  #### Output [#output-7]

  | Parameter | Type | Description |
  | - | - | - |
  | `file` | file | Downloaded media stored as a workflow file |
  | `mediaId` | string | WhatsApp media ID that was downloaded |
  | `mimeType` | string | MIME type reported by WhatsApp |
  | `fileSize` | number | Size of the downloaded media in bytes |
  | `sha256` | string | SHA-256 hash WhatsApp reported for the media, for integrity checks |
</ReferenceDetails>

## Triggers [#triggers]

A trigger starts a workflow when a supported event occurs in this service.

### WhatsApp Webhook [#whatsapp-webhook]

Trigger workflow from WhatsApp incoming messages and message status webhooks

<ReferenceDetails label="Configuration and outputs">
  #### Configuration [#configuration]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `verificationToken` | string | Yes | Enter any secure token here. You'll need to provide the same token in your WhatsApp Business Platform dashboard. |
  | `appSecret` | string | Yes | Required for WhatsApp POST signature verification. Sim uses it to validate the X-Hub-Signature-256 header on every webhook delivery. |

  #### Output [#output-8]

  | Parameter | Type | Description |
  | - | - | - |
  | `eventType` | string | Webhook classification such as incoming\_message, message\_status, or mixed |
  | `messageId` | string | First WhatsApp message identifier (wamid) found in the webhook batch |
  | `from` | string | Sender phone number from the first incoming message in the batch |
  | `recipientId` | string | Recipient phone number from the first status update in the batch |
  | `phoneNumberId` | string | Business phone number ID from the first message or status item in the batch |
  | `displayPhoneNumber` | string | Business display phone number from the first message or status item in the batch |
  | `text` | string | Text body from the first incoming text message in the batch |
  | `timestamp` | string | Timestamp from the first message or status item in the batch |
  | `messageType` | string | Type of the first incoming message in the batch (text, image, system, etc.) |
  | `mediaId` | string | Media asset ID from the first incoming media message. Pass to the Download Media operation to fetch the file. Expires after 7 days. |
  | `mediaMimeType` | string | MIME type of the first incoming media message |
  | `caption` | string | Caption on the first incoming image, video, or document message |
  | `status` | string | First outgoing message status in the batch, such as sent, delivered, read, or failed |
  | `contact` | json | First sender contact in the batch (wa\_id, profile.name) |
  | `webhookContacts` | json | All sender contact profiles from the webhook batch |
  | `messages` | json | All incoming message objects from the webhook batch, flattened across entries/changes |
  | `statuses` | json | All message status objects from the webhook batch, flattened across entries/changes |
  | `conversation` | json | Conversation metadata from the first status update in the batch (id, expiration\_timestamp, origin.type) |
  | `pricing` | json | Pricing metadata from the first status update in the batch (billable, pricing\_model, category) |
  | `raw` | json | Complete structured webhook payload from WhatsApp |
</ReferenceDetails>