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, interactive, and Flow messages, react to messages, and mark messages as read through the WhatsApp Cloud API. Manage message templates, the business profile, and the phone numbers on your WhatsApp Business Account. Free-form messages (text, media, interactive, and Flows) only reach a contact within the 24-hour customer service window that opens each time they message you — outside that window WhatsApp requires a pre-approved template. Trigger workflows on incoming messages, completed Flows, delivery status updates, and template review changes.
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 |
templates | array | Templates from List Templates (id, name, status, category, language, qualityScore, rejectedReason, components) |
count | number | Number of items returned by a list operation |
before | string | Cursor for the previous page of a list operation |
after | string | Cursor for the next page of a list operation |
hasMore | boolean | Whether a list operation has another page |
templateId | string | ID of the template created by Create Template |
id | string | Template ID from Get Template |
name | string | Template name from Get Template |
category | string | Template category from Get or Create Template |
language | string | Template language from Get Template |
parameterFormat | string | Template variable format from Get Template |
previousCategory | string | Template category before Meta recategorized it |
rejectedReason | string | Why the template was rejected |
qualityScore | string | Template quality rating: GREEN, YELLOW, RED, or UNKNOWN |
qualityScoreDate | number | Unix timestamp when the template quality rating was last updated |
components | json | Template components from Get Template |
phoneNumbers | array | Phone numbers from List Phone Numbers (id, displayPhoneNumber, verifiedName, status, qualityRating, messagingLimitTier) |
about | string | Business profile About text |
address | string | Business profile address |
description | string | Business profile description |
email | string | Business profile email |
profilePictureUrl | string | Business profile picture URL |
websites | array | Business profile websites |
vertical | string | Business profile industry |
eventType | string | Webhook classification: incoming_message, message_status, template_status_update, 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 trigger batch (sent, delivered, read, failed), or the template review status from Get Template / Create Template |
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 (id, expiration_timestamp, origin.type); only sent for free entry point conversations since Graph v24.0 |
pricing | json | Pricing from the first status update (billable, pricing_model, type, category, subtype) |
errors | json | Errors from the first failed status in the batch (code, title, message, details) |
errorCode | number | Error code from the first failed status, e.g. 131047 when the 24-hour window has closed |
errorTitle | string | Error title from the first failed status |
errorDetails | string | Error details from the first failed status |
interactiveType | string | Interactive reply type: button_reply, list_reply, or nfm_reply (completed Flow) |
flowResponse | json | First completed Flow in the batch with the parsed form answers in responseJson |
flowToken | string | flow_token from the first completed Flow |
templateStatusUpdate | json | First template status change (event, templateId, templateName, templateLanguage, reason) |
templateStatusUpdates | json | All template status changes in the webhook batch |
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 |
templates | array | Templates from List Templates (id, name, status, category, language, qualityScore, rejectedReason, components) |
count | number | Number of items returned by a list operation |
before | string | Cursor for the previous page of a list operation |
after | string | Cursor for the next page of a list operation |
hasMore | boolean | Whether a list operation has another page |
templateId | string | ID of the template created by Create Template |
id | string | Template ID from Get Template |
name | string | Template name from Get Template |
category | string | Template category from Get or Create Template |
language | string | Template language from Get Template |
parameterFormat | string | Template variable format from Get Template |
previousCategory | string | Template category before Meta recategorized it |
rejectedReason | string | Why the template was rejected |
qualityScore | string | Template quality rating: GREEN, YELLOW, RED, or UNKNOWN |
qualityScoreDate | number | Unix timestamp when the template quality rating was last updated |
components | json | Template components from Get Template |
phoneNumbers | array | Phone numbers from List Phone Numbers (id, displayPhoneNumber, verifiedName, status, qualityRating, messagingLimitTier) |
about | string | Business profile About text |
address | string | Business profile address |
description | string | Business profile description |
email | string | Business profile email |
profilePictureUrl | string | Business profile picture URL |
websites | array | Business profile websites |
vertical | string | Business profile industry |
eventType | string | Webhook classification: incoming_message, message_status, template_status_update, 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 trigger batch (sent, delivered, read, failed), or the template review status from Get Template / Create Template |
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 (id, expiration_timestamp, origin.type); only sent for free entry point conversations since Graph v24.0 |
pricing | json | Pricing from the first status update (billable, pricing_model, type, category, subtype) |
errors | json | Errors from the first failed status in the batch (code, title, message, details) |
errorCode | number | Error code from the first failed status, e.g. 131047 when the 24-hour window has closed |
errorTitle | string | Error title from the first failed status |
errorDetails | string | Error details from the first failed status |
interactiveType | string | Interactive reply type: button_reply, list_reply, or nfm_reply (completed Flow) |
flowResponse | json | First completed Flow in the batch with the parsed form answers in responseJson |
flowToken | string | flow_token from the first completed Flow |
templateStatusUpdate | json | First template status change (event, templateId, templateName, templateLanguage, reason) |
templateStatusUpdates | json | All template status changes in the webhook batch |
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 |
templates | array | Templates from List Templates (id, name, status, category, language, qualityScore, rejectedReason, components) |
count | number | Number of items returned by a list operation |
before | string | Cursor for the previous page of a list operation |
after | string | Cursor for the next page of a list operation |
hasMore | boolean | Whether a list operation has another page |
templateId | string | ID of the template created by Create Template |
id | string | Template ID from Get Template |
name | string | Template name from Get Template |
category | string | Template category from Get or Create Template |
language | string | Template language from Get Template |
parameterFormat | string | Template variable format from Get Template |
previousCategory | string | Template category before Meta recategorized it |
rejectedReason | string | Why the template was rejected |
qualityScore | string | Template quality rating: GREEN, YELLOW, RED, or UNKNOWN |
qualityScoreDate | number | Unix timestamp when the template quality rating was last updated |
components | json | Template components from Get Template |
phoneNumbers | array | Phone numbers from List Phone Numbers (id, displayPhoneNumber, verifiedName, status, qualityRating, messagingLimitTier) |
about | string | Business profile About text |
address | string | Business profile address |
description | string | Business profile description |
email | string | Business profile email |
profilePictureUrl | string | Business profile picture URL |
websites | array | Business profile websites |
vertical | string | Business profile industry |
eventType | string | Webhook classification: incoming_message, message_status, template_status_update, 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 trigger batch (sent, delivered, read, failed), or the template review status from Get Template / Create Template |
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 (id, expiration_timestamp, origin.type); only sent for free entry point conversations since Graph v24.0 |
pricing | json | Pricing from the first status update (billable, pricing_model, type, category, subtype) |
errors | json | Errors from the first failed status in the batch (code, title, message, details) |
errorCode | number | Error code from the first failed status, e.g. 131047 when the 24-hour window has closed |
errorTitle | string | Error title from the first failed status |
errorDetails | string | Error details from the first failed status |
interactiveType | string | Interactive reply type: button_reply, list_reply, or nfm_reply (completed Flow) |
flowResponse | json | First completed Flow in the batch with the parsed form answers in responseJson |
flowToken | string | flow_token from the first completed Flow |
templateStatusUpdate | json | First template status change (event, templateId, templateName, templateLanguage, reason) |
templateStatusUpdates | json | All template status changes in the webhook batch |
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 |
templates | array | Templates from List Templates (id, name, status, category, language, qualityScore, rejectedReason, components) |
count | number | Number of items returned by a list operation |
before | string | Cursor for the previous page of a list operation |
after | string | Cursor for the next page of a list operation |
hasMore | boolean | Whether a list operation has another page |
templateId | string | ID of the template created by Create Template |
id | string | Template ID from Get Template |
name | string | Template name from Get Template |
category | string | Template category from Get or Create Template |
language | string | Template language from Get Template |
parameterFormat | string | Template variable format from Get Template |
previousCategory | string | Template category before Meta recategorized it |
rejectedReason | string | Why the template was rejected |
qualityScore | string | Template quality rating: GREEN, YELLOW, RED, or UNKNOWN |
qualityScoreDate | number | Unix timestamp when the template quality rating was last updated |
components | json | Template components from Get Template |
phoneNumbers | array | Phone numbers from List Phone Numbers (id, displayPhoneNumber, verifiedName, status, qualityRating, messagingLimitTier) |
about | string | Business profile About text |
address | string | Business profile address |
description | string | Business profile description |
email | string | Business profile email |
profilePictureUrl | string | Business profile picture URL |
websites | array | Business profile websites |
vertical | string | Business profile industry |
eventType | string | Webhook classification: incoming_message, message_status, template_status_update, 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 trigger batch (sent, delivered, read, failed), or the template review status from Get Template / Create Template |
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 (id, expiration_timestamp, origin.type); only sent for free entry point conversations since Graph v24.0 |
pricing | json | Pricing from the first status update (billable, pricing_model, type, category, subtype) |
errors | json | Errors from the first failed status in the batch (code, title, message, details) |
errorCode | number | Error code from the first failed status, e.g. 131047 when the 24-hour window has closed |
errorTitle | string | Error title from the first failed status |
errorDetails | string | Error details from the first failed status |
interactiveType | string | Interactive reply type: button_reply, list_reply, or nfm_reply (completed Flow) |
flowResponse | json | First completed Flow in the batch with the parsed form answers in responseJson |
flowToken | string | flow_token from the first completed Flow |
templateStatusUpdate | json | First template status change (event, templateId, templateName, templateLanguage, reason) |
templateStatusUpdates | json | All template status changes in the webhook batch |
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 |
templates | array | Templates from List Templates (id, name, status, category, language, qualityScore, rejectedReason, components) |
count | number | Number of items returned by a list operation |
before | string | Cursor for the previous page of a list operation |
after | string | Cursor for the next page of a list operation |
hasMore | boolean | Whether a list operation has another page |
templateId | string | ID of the template created by Create Template |
id | string | Template ID from Get Template |
name | string | Template name from Get Template |
category | string | Template category from Get or Create Template |
language | string | Template language from Get Template |
parameterFormat | string | Template variable format from Get Template |
previousCategory | string | Template category before Meta recategorized it |
rejectedReason | string | Why the template was rejected |
qualityScore | string | Template quality rating: GREEN, YELLOW, RED, or UNKNOWN |
qualityScoreDate | number | Unix timestamp when the template quality rating was last updated |
components | json | Template components from Get Template |
phoneNumbers | array | Phone numbers from List Phone Numbers (id, displayPhoneNumber, verifiedName, status, qualityRating, messagingLimitTier) |
about | string | Business profile About text |
address | string | Business profile address |
description | string | Business profile description |
email | string | Business profile email |
profilePictureUrl | string | Business profile picture URL |
websites | array | Business profile websites |
vertical | string | Business profile industry |
eventType | string | Webhook classification: incoming_message, message_status, template_status_update, 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 trigger batch (sent, delivered, read, failed), or the template review status from Get Template / Create Template |
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 (id, expiration_timestamp, origin.type); only sent for free entry point conversations since Graph v24.0 |
pricing | json | Pricing from the first status update (billable, pricing_model, type, category, subtype) |
errors | json | Errors from the first failed status in the batch (code, title, message, details) |
errorCode | number | Error code from the first failed status, e.g. 131047 when the 24-hour window has closed |
errorTitle | string | Error title from the first failed status |
errorDetails | string | Error details from the first failed status |
interactiveType | string | Interactive reply type: button_reply, list_reply, or nfm_reply (completed Flow) |
flowResponse | json | First completed Flow in the batch with the parsed form answers in responseJson |
flowToken | string | flow_token from the first completed Flow |
templateStatusUpdate | json | First template status change (event, templateId, templateName, templateLanguage, reason) |
templateStatusUpdates | json | All template status changes in the webhook batch |
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 |
Send an interactive WhatsApp Flow — a multi-screen form such as a booking, sign-up, or survey — behind a call-to-action button. Like other free-form messages it only delivers within 24 hours of the contact last messaging you; outside that window send a template with a Flow button. The completed form arrives on the WhatsApp trigger as a Flow response.
| Parameter | Type | Required | Description |
|---|
phoneNumber | string | Yes | Recipient phone number with country code (e.g., +14155552671) |
bodyText | string | Yes | Message body shown above the Flow button |
flowId | string | No | Flow ID from WhatsApp Manager. Provide either the Flow ID or the Flow name. |
flowName | string | No | Flow name. Provide either the Flow name or the Flow ID, not both. |
flowCta | string | Yes | Button label that opens the Flow (e.g., "Book now"), ideally 30 characters or fewer with no emoji |
flowToken | string | No | Your own identifier echoed back in the Flow response (e.g., a lead or ticket ID). The response does not include the Flow ID, so use this to match replies. |
flowAction | string | No | navigate (default) opens a screen directly; data_exchange calls your Flow endpoint first |
flowScreen | string | No | ID of the entry screen to open with the navigate action (defaults to the Flow entry screen) |
flowData | json | No | Non-empty JSON object of input data for the first screen (navigate action only) |
flowMode | string | No | published (default) sends the last published version; draft sends the current draft for testing |
headerText | string | No | Optional plain-text header (max 60 characters) |
footerText | string | No | Optional footer text (max 60 characters) |
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 |
templates | array | Templates from List Templates (id, name, status, category, language, qualityScore, rejectedReason, components) |
count | number | Number of items returned by a list operation |
before | string | Cursor for the previous page of a list operation |
after | string | Cursor for the next page of a list operation |
hasMore | boolean | Whether a list operation has another page |
templateId | string | ID of the template created by Create Template |
id | string | Template ID from Get Template |
name | string | Template name from Get Template |
category | string | Template category from Get or Create Template |
language | string | Template language from Get Template |
parameterFormat | string | Template variable format from Get Template |
previousCategory | string | Template category before Meta recategorized it |
rejectedReason | string | Why the template was rejected |
qualityScore | string | Template quality rating: GREEN, YELLOW, RED, or UNKNOWN |
qualityScoreDate | number | Unix timestamp when the template quality rating was last updated |
components | json | Template components from Get Template |
phoneNumbers | array | Phone numbers from List Phone Numbers (id, displayPhoneNumber, verifiedName, status, qualityRating, messagingLimitTier) |
about | string | Business profile About text |
address | string | Business profile address |
description | string | Business profile description |
email | string | Business profile email |
profilePictureUrl | string | Business profile picture URL |
websites | array | Business profile websites |
vertical | string | Business profile industry |
eventType | string | Webhook classification: incoming_message, message_status, template_status_update, 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 trigger batch (sent, delivered, read, failed), or the template review status from Get Template / Create Template |
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 (id, expiration_timestamp, origin.type); only sent for free entry point conversations since Graph v24.0 |
pricing | json | Pricing from the first status update (billable, pricing_model, type, category, subtype) |
errors | json | Errors from the first failed status in the batch (code, title, message, details) |
errorCode | number | Error code from the first failed status, e.g. 131047 when the 24-hour window has closed |
errorTitle | string | Error title from the first failed status |
errorDetails | string | Error details from the first failed status |
interactiveType | string | Interactive reply type: button_reply, list_reply, or nfm_reply (completed Flow) |
flowResponse | json | First completed Flow in the batch with the parsed form answers in responseJson |
flowToken | string | flow_token from the first completed Flow |
templateStatusUpdate | json | First template status change (event, templateId, templateName, templateLanguage, reason) |
templateStatusUpdates | json | All template status changes in the webhook batch |
raw | json | Full structured WhatsApp webhook payload |
error | string | Error information if sending fails |
List message templates on a WhatsApp Business Account with their review status and quality rating. Templates are required to message a contact outside the 24-hour customer service window, and only APPROVED templates can be sent.
| Parameter | Type | Required | Description |
|---|
templateName | string | No | Only return templates with this exact name |
templateStatus | string | No | Only return templates in this review status (e.g., APPROVED, PENDING, REJECTED, PAUSED, DISABLED) |
templateCategory | string | No | Only return templates in this category (MARKETING, UTILITY, AUTHENTICATION) |
templateLanguage | string | No | Only return templates in this language and locale code (e.g., en_US) |
qualityScore | string | No | Only return templates with this quality rating (GREEN, YELLOW, RED, UNKNOWN) |
limit | number | No | Maximum number of templates to return in this page |
after | string | No | Pagination cursor from a previous response to fetch the next page |
before | string | No | Pagination cursor from a previous response to fetch the previous page |
businessAccountId | string | Yes | WhatsApp Business Account (WABA) ID (from WhatsApp Manager) |
| Parameter | Type | Description |
|---|
templates | array | Message templates on the account |
count | number | Number of templates returned in this page |
Get one WhatsApp message template by ID, including its components, review status, rejection reason, and quality rating.
| Parameter | Type | Required | Description |
|---|
templateId | string | Yes | Message template ID (from List Templates or Create Template) |
| 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 |
templates | array | Templates from List Templates (id, name, status, category, language, qualityScore, rejectedReason, components) |
count | number | Number of items returned by a list operation |
before | string | Cursor for the previous page of a list operation |
after | string | Cursor for the next page of a list operation |
hasMore | boolean | Whether a list operation has another page |
templateId | string | ID of the template created by Create Template |
id | string | Template ID from Get Template |
name | string | Template name from Get Template |
category | string | Template category from Get or Create Template |
language | string | Template language from Get Template |
parameterFormat | string | Template variable format from Get Template |
previousCategory | string | Template category before Meta recategorized it |
rejectedReason | string | Why the template was rejected |
qualityScore | string | Template quality rating: GREEN, YELLOW, RED, or UNKNOWN |
qualityScoreDate | number | Unix timestamp when the template quality rating was last updated |
components | json | Template components from Get Template |
phoneNumbers | array | Phone numbers from List Phone Numbers (id, displayPhoneNumber, verifiedName, status, qualityRating, messagingLimitTier) |
about | string | Business profile About text |
address | string | Business profile address |
description | string | Business profile description |
email | string | Business profile email |
profilePictureUrl | string | Business profile picture URL |
websites | array | Business profile websites |
vertical | string | Business profile industry |
eventType | string | Webhook classification: incoming_message, message_status, template_status_update, 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 trigger batch (sent, delivered, read, failed), or the template review status from Get Template / Create Template |
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 (id, expiration_timestamp, origin.type); only sent for free entry point conversations since Graph v24.0 |
pricing | json | Pricing from the first status update (billable, pricing_model, type, category, subtype) |
errors | json | Errors from the first failed status in the batch (code, title, message, details) |
errorCode | number | Error code from the first failed status, e.g. 131047 when the 24-hour window has closed |
errorTitle | string | Error title from the first failed status |
errorDetails | string | Error details from the first failed status |
interactiveType | string | Interactive reply type: button_reply, list_reply, or nfm_reply (completed Flow) |
flowResponse | json | First completed Flow in the batch with the parsed form answers in responseJson |
flowToken | string | flow_token from the first completed Flow |
templateStatusUpdate | json | First template status change (event, templateId, templateName, templateLanguage, reason) |
templateStatusUpdates | json | All template status changes in the webhook batch |
raw | json | Full structured WhatsApp webhook payload |
error | string | Error information if sending fails |
Submit a new message template for review. Templates start as PENDING and can only be sent once APPROVED; they are how you message contacts outside the 24-hour customer service window.
| Parameter | Type | Required | Description |
|---|
templateName | string | Yes | Template name: lowercase letters, numbers, and underscores only (max 512 characters) |
templateCategory | string | Yes | Template category: MARKETING, UTILITY, or AUTHENTICATION |
languageCode | string | Yes | Template language and locale code (e.g., en_US) |
templateComponents | json | Yes | Components array, e.g. [{"type":"BODY","text":"Hi {{1}}, your order {{2}} shipped.","example":{"body_text":[["Ana","1234"]]}}]. HEADER, BODY, and FOOTER need text; templates with variables need examples to be approved. |
parameterFormat | string | No | Variable format: positional ({{1}}) or named ({{first_name}}). Defaults to positional. |
allowCategoryChange | boolean | No | Let Meta reassign the category instead of rejecting a miscategorized template |
businessAccountId | string | Yes | WhatsApp Business Account (WABA) ID (from WhatsApp Manager) |
| Parameter | Type | Description |
|---|
templateId | string | ID of the new template |
status | string | Initial review status, usually PENDING. Watch template status updates for approval. |
category | string | Category Meta assigned to the template |
Delete a message template. With only a name, every language version of that template is deleted; add the template ID to delete just one. A deleted approved template name cannot be reused for 30 days.
| Parameter | Type | Required | Description |
|---|
templateName | string | Yes | Name of the template to delete |
templateId | string | No | Template ID to delete only that language version |
businessAccountId | string | Yes | WhatsApp Business Account (WABA) ID (from WhatsApp Manager) |
| Parameter | Type | Description |
|---|
success | boolean | Whether WhatsApp deleted the template |
Get the WhatsApp business profile customers see for a phone number: about text, address, description, email, websites, industry, and profile picture.
| Parameter | Type | Required | Description |
|---|
phoneNumberId | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |
| Parameter | Type | Description |
|---|
about | string | Profile About text |
address | string | Business address |
description | string | Business description |
email | string | Contact email |
profilePictureUrl | string | URL of the profile picture |
websites | array | Websites listed on the profile |
vertical | string | Industry of the business (e.g., RETAIL, HEALTH, PROF_SERVICES) |
Update the WhatsApp business profile customers see for a phone number. Only the fields you provide are changed.
| Parameter | Type | Required | Description |
|---|
about | string | No | About text shown on the profile |
address | string | No | Business address (free text, max 256 characters) |
profileDescription | string | No | Business description |
email | string | No | Contact email address |
websites | json | No | Website URLs as a JSON array or comma-separated list |
vertical | string | No | Industry of the business: OTHER, AUTO, BEAUTY, APPAREL, EDU, ENTERTAIN, EVENT_PLAN, FINANCE, GROCERY, GOVT, HOTEL, HEALTH, NONPROFIT, PROF_SERVICES, RETAIL, TRAVEL, RESTAURANT, ALCOHOL, ONLINE_GAMBLING, PHYSICAL_GAMBLING, OTC_DRUGS |
profilePictureHandle | string | No | Profile picture handle returned by the Meta Resumable Upload API |
phoneNumberId | string | Yes | WhatsApp Business Phone Number ID (from Meta Business Suite) |
| Parameter | Type | Description |
|---|
success | boolean | Whether WhatsApp saved the profile changes |
List the business phone numbers on a WhatsApp Business Account with their connection status, quality rating, and messaging limit tier — the daily cap on contacts you can message outside the 24-hour customer service window.
| Parameter | Type | Required | Description |
|---|
limit | number | No | Maximum number of phone numbers to return (1-100) |
after | string | No | Pagination cursor from a previous response to fetch the next page |
before | string | No | Pagination cursor from a previous response to fetch the previous page |
businessAccountId | string | Yes | WhatsApp Business Account (WABA) ID (from WhatsApp Manager) |
| Parameter | Type | Description |
|---|
phoneNumbers | array | Business phone numbers on the account |
↳ id | string | Phone number ID used by the messaging operations |
↳ displayPhoneNumber | string | Phone number in display format |
↳ verifiedName | string | Display name approved for the number |
↳ status | string | Connection status (CONNECTED, PENDING, FLAGGED, RESTRICTED, RATE_LIMITED, DISCONNECTED, BANNED, MIGRATED, DELETED). Only CONNECTED numbers can send. |
↳ qualityRating | string | Quality rating: GREEN, YELLOW, RED, or UNKNOWN |
↳ messagingLimitTier | string | Messaging limit tier (TIER_50, TIER_250, TIER_1K, TIER_10K, TIER_100K, TIER_UNLIMITED). Since v24.0 this reflects the business portfolio limit. |
↳ codeVerificationStatus | string | Ownership verification status: VERIFIED, NOT_VERIFIED, or EXPIRED |
↳ isOfficialBusinessAccount | boolean | Whether the number has Official Business Account status |
↳ accountMode | string | LIVE or SANDBOX |
count | number | Number of phone numbers returned in this page |
A Trigger is a block that starts a workflow when an event happens in this service.
Trigger workflow from WhatsApp incoming messages (including completed Flow forms), outgoing message status updates (sent, delivered, read, failed), and template review status changes
| 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. Agent Serve uses it to validate the X-Hub-Signature-256 header on every webhook delivery. |
eventTypes | string | No | Run only for the selected event types. Leave empty to run on every delivery. Status updates fire for every sent, delivered, read, and failed message, so select only what the workflow handles. |
| Parameter | Type | Description |
|---|
eventType | string | Webhook classification: incoming_message, message_status, template_status_update, 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. Failed statuses include an errors array. |
conversation | json | Conversation metadata from the first status update (id, expiration_timestamp, origin.type). Since Graph v24.0 WhatsApp only sends it for free entry point conversations. |
pricing | json | Pricing from the first status update (billable, pricing_model, type, category, and subtype when applicable). Sent with sent, delivered, or read statuses. |
errors | json | Errors from the first failed status in the batch, each with code, title, message, details, and href |
errorCode | number | Error code from the first failed status (e.g., 131047 when the 24-hour window has closed and a template is required) |
errorTitle | string | Error title from the first failed status |
errorDetails | string | Error details from the first failed status |
interactiveType | string | Interactive reply type of the first incoming message: button_reply, list_reply, or nfm_reply (completed Flow) |
flowResponse | json | First completed WhatsApp Flow in the batch: name, body, responseJson (the parsed form answers, including flow_token), and responseJsonRaw |
flowToken | string | flow_token from the first completed Flow, matching the token sent with Send Flow |
templateStatusUpdate | json | First template status change: event (APPROVED, REJECTED, PAUSED, DISABLED, ARCHIVED, ...), templateId, templateName, templateLanguage, templateCategory, reason, rejectionInfo, disableInfo, otherInfo |
templateStatusUpdates | json | All template status changes in the webhook batch |
raw | json | Complete structured webhook payload from WhatsApp |