Use WhatsApp 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.
Integrate WhatsApp into the workflow. 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.
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.
| 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 |
| 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 |
Send a pre-approved WhatsApp template message. Required to start a conversation or to message a user outside the 24-hour customer service window.
| 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) |
| 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 |
Send an image, document, video, audio, or sticker message. Accepts an uploaded file, a media ID, or a public link.
| 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) |
| 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 |
Send an interactive WhatsApp message with reply buttons or a selectable list.
| 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) |
| 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 |
React to a WhatsApp message with an emoji. Send an empty emoji to remove an existing reaction.
| 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) |
| 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 |
Mark a received WhatsApp message as read so the sender sees blue checkmarks, optionally showing a typing indicator.
| 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) |
| Parameter | Type | Description |
|---|
success | boolean | Whether the message was successfully marked as read |
Upload a file to WhatsApp and get a media ID for sending. Uploaded media is retained for 30 days and can back many sends.
| 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) |
| 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 |
Download media a customer sent you. Takes the media ID from an incoming WhatsApp message and stores the file in the workflow.
| 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) |
| 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 |
A Trigger is a block that starts a workflow when an event happens in this service.
Trigger workflow from WhatsApp incoming messages and message status webhooks
| 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. |
| 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 |