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