WhatsApp

WhatsApp is a globally popular messaging platform that enables secure, reliable communication between individuals and businesses.

WhatsApp Business API provides organizations with powerful capabilities to:

Engage customers: Send personalized messages, notifications, and updates directly to customers' preferred messaging app
Automate conversations: Create interactive chatbots and automated response systems for common inquiries
Enhance support: Provide real-time customer service through a familiar interface with rich media support
Drive conversions: Facilitate transactions and follow-ups with customers in a secure, compliant environment

In Sim, the WhatsApp integration enables your agents to leverage these messaging capabilities as part of their workflows. This creates opportunities for sophisticated customer engagement scenarios like appointment reminders, verification codes, alerts, and interactive conversations. The integration bridges the gap between your AI workflows and customer communication channels, allowing your agents to deliver timely, relevant information directly to users' mobile devices. By connecting Sim with WhatsApp, you can build intelligent agents that engage customers through their preferred messaging platform, enhancing user experience while automating routine messaging tasks.

Usage Instructions

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.

Actions

`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.

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

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

`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.

Input

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

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

`whatsapp_send_media`

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

Input

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

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

`whatsapp_send_interactive`

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

Input

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

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

`whatsapp_send_reaction`

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

Input

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

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

`whatsapp_mark_read`

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

Input

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

Parameter	Type	Description
`success`	boolean	Whether the message was successfully marked as read

`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.

Input

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

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

`whatsapp_get_media`

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

Input

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

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

Parameter	Type	Required	Description
`verificationToken`	string	Yes	Enter any secure token here. You
`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

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

WhatsApp

Usage Instructions

Actions

`whatsapp_send_message`

Input

Output

`whatsapp_send_template`

Input

Output

`whatsapp_send_media`

Input

Output

`whatsapp_send_interactive`

Input

Output

`whatsapp_send_reaction`

Input

Output

`whatsapp_mark_read`

Input

Output

`whatsapp_upload_media`

Input

Output

`whatsapp_get_media`

Input

Output

Triggers

WhatsApp Webhook

Configuration

Output

On this page