Skip to main content

WhatsApp Messages

Read and answer WhatsApp chats of your own WhatsApp Business number through the same DM endpoints used for Instagram and Messenger.

WhatsApp is a messaging channel

WhatsApp is not a publishing destination. It does not appear in /upload and cannot receive posts: you use it only to send and receive messages with /api/uploadposts/dms/*.


Connect a WhatsApp number​

You connect your own WhatsApp Business number with Meta's official Embedded Signup window (Connect WhatsApp > Continue with Facebook), from the Upload-Post dashboard or from the white-label connect page your end users open with a JWT link. There is no credential to send through the API. A number already used in the WhatsApp Business app can be connected too and keeps working on the phone. A number belongs to one Upload-Post account at a time: connecting it from another account moves it there. When it is connected you get the social_account_connected webhook with platform: "whatsapp".

Requirements, the steps of Meta's window, the WhatsApp Business app option and troubleshooting: How to connect WhatsApp.

Billing

Meta charges WhatsApp messages (for example templates sent outside the 24-hour window) to your WhatsApp Business account, with the payment method you set up with Meta. Upload-Post does not bill or resell WhatsApp conversations. See Meta's pricing for the current rates.


The 24-hour customer service window​

  • When a person writes to your number, you can answer with free text, media and replies for the next 24 hours.
  • Outside that window WhatsApp only accepts an approved template (see Templates). Templates start a new conversation; when the person answers, the 24-hour window opens again.
  • Reactions from the person do not open the window.
  • The window is per person. Get Conversations tells you until when it is open with window_open_until.

If you send free text outside the window, the API answers 400 with error_code: "whatsapp_template_required". Later free-text sends to that person are refused up front with dm_window_blocked until they write again; template sends are always allowed.


Send a Message​

Endpoint​

POST /api/uploadposts/dms/send

Headers​

NameValueDescription
AuthorizationApikey your-api-key-hereYour API key for authentication

Body Parameters (JSON)​

NameTypeRequiredDescription
platformStringYes"whatsapp".
userStringYesProfile username (as configured in Upload-Post) that has the WhatsApp number connected.
recipient_idStringYesThe person's phone number in international format, with country code. 34600111222, +34 600 111 222 and +34-600-111-222 are all accepted (7 to 15 digits).
messageStringYes, unless attachments, template, location, contacts, reaction or sender_action is sentText, up to 4096 characters. Links get a preview.
attachments / attachmentObject or arrayNoUp to 10 items {type, url} or {type, media_id}. See below.
templateObjectNoAn approved template: {name, language, components}. When present, message and attachments are ignored. Works outside the 24-hour window.
reply_toStringNoId of a message in the chat (wamid...) to quote it in your reply.
locationObjectNoA location pin: {latitude, longitude, name?, address?}. If message is also sent, it goes first as a text message.
contactsArrayNo1 to 10 contact cards in Meta's contact format. Shortcuts are accepted: name can be a plain string and phones a plain string.
buttonsArrayNoUp to 3 reply buttons {id?, title} (title up to 20 characters). Needs message as the body (up to 1024 characters).
listObjectNoA list menu: {button, sections}. See Interactive messages. Needs message as the body.
cta_urlObjectNoA call-to-action link button: {display_text, url}. Needs message as the body.
headerStringNoInteractive messages only: header text, up to 60 characters.
footerStringNoInteractive messages only: footer text, up to 60 characters.
reactionObject or StringNoReact to a message: {message_id, emoji}. An empty emoji removes your reaction. Also accepted as reaction: "👍" plus a top-level message_id. See Reactions.
message_idStringWith reaction or sender_actionThe wamid of the incoming message to react to or mark as read.
sender_actionStringNomark_read marks an incoming message as read (blue ticks). typing_on also shows the typing indicator. See Mark as read and typing.
typingBooleanNoWith sender_action: "mark_read", also shows the typing indicator.

Attachments​

FieldDescription
typeimage, video, audio, document or sticker (file is accepted as document).
urlPublic https:// URL of the file. WhatsApp downloads it, so it must be reachable without login.
media_idInstead of url: a WhatsApp media id, either one you got from Upload Media or one received in an incoming message.
captionOptional, for image, video and document (max 1024 characters).
filenameOptional, for document: the name shown in the chat.

When you send message together with a single image, video or document and no caption, the text becomes the caption (if it fits in 1024 characters). Otherwise the text and each attachment are sent as separate messages, in that order.

Interactive messages​

Interactive messages carry tappable options. They are free-form, so they only work inside the 24-hour window, and they cannot carry attachments. message is required and becomes the body (up to 1024 characters). Add header and footer (text, up to 60 characters each) if you want them. Send only one of buttons, list or cta_url per request.

TypeFields
buttonsUp to 3 items {id?, title}. title up to 20 characters; id is generated if you omit it.
list{button, sections}. button is the label that opens the menu (up to 20 characters). sections is an array of {title?, rows}; each row is {id?, title, description?} with title up to 24 and description up to 72 characters. Max 10 rows in total.
cta_url{display_text, url}. display_text up to 20 characters; url must be https://.

When the person taps an option you receive an incoming message of type interactive (list or reply button) or button (template quick reply), with the id and title you set. Read it in Get Conversations or the dm_received webhook.

Reactions​

{ "platform": "whatsapp", "user": "my-profile", "recipient_id": "34600111222",
"reaction": { "message_id": "wamid.HBgL...", "emoji": "👍" } }

Send an empty emoji ("") to remove your reaction. Reactions do not count towards the daily DM limit. They are not separate messages in conversations: they appear on the reacted message (see Get Conversations).

Mark as read and typing​

sender_action: "mark_read" with the message_id (wamid) of an incoming message marks it as read, so the person sees blue ticks. Add typing: true (or use sender_action: "typing_on") to also show the typing indicator while you prepare an answer. It is not a message: it needs no message, does not count towards the daily DM limit and works outside the 24-hour window.

Template object​

FieldDescription
nameTemplate name, exactly as approved.
languageLanguage code of the approved version, for example en_US or es. Default en_US.
componentsOptional. Values for the template's variables, in Meta's format (header, body, button components with parameters).

Example Requests​

Free text inside the 24-hour window:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "whatsapp",
"user": "my-profile",
"recipient_id": "34600111222",
"message": "Hi Jane! Your order has shipped."
}'

Image with caption, replying to a message:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "whatsapp",
"user": "my-profile",
"recipient_id": "34600111222",
"message": "Here is your invoice",
"reply_to": "wamid.HBgLMzQ2MDAxMTEyMjIVAgASGBQzQTk...",
"attachments": [
{ "type": "document", "url": "https://example.com/invoice-1042.pdf", "filename": "invoice-1042.pdf" }
]
}'

Upload a file, then send it as a document:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/media \
-H 'Authorization: Apikey your-api-key-here' \
-F 'platform=whatsapp' \
-F 'user=my-profile' \
-F 'type=document' \
-F '[email protected]'
# -> {"success": true, "platform": "whatsapp", "type": "document", "media_id": "1037543291543636", ...}

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "whatsapp",
"user": "my-profile",
"recipient_id": "34600111222",
"message": "Here is your invoice",
"attachments": [
{ "type": "document", "media_id": "1037543291543636", "filename": "invoice-1042.pdf" }
]
}'

Reply buttons:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "whatsapp",
"user": "my-profile",
"recipient_id": "34600111222",
"message": "Was your order delivered correctly?",
"footer": "Acme Store",
"buttons": [
{ "id": "yes", "title": "Yes" },
{ "id": "no", "title": "No, there is a problem" }
]
}'

Location:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "whatsapp",
"user": "my-profile",
"recipient_id": "34600111222",
"message": "Our store is here:",
"location": { "latitude": 40.4168, "longitude": -3.7038, "name": "Acme Store", "address": "Calle Mayor 1, Madrid" }
}'

Reaction:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "whatsapp",
"user": "my-profile",
"recipient_id": "34600111222",
"reaction": { "message_id": "wamid.HBgLMzQ2MDAxMTEyMjIVAgASGBQzQTk...", "emoji": "👍" }
}'

Mark as read, with typing indicator:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "whatsapp",
"user": "my-profile",
"recipient_id": "34600111222",
"sender_action": "mark_read",
"message_id": "wamid.HBgLMzQ2MDAxMTEyMjIVAgASGBQzQTk...",
"typing": true
}'

Approved template (outside the window):

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "whatsapp",
"user": "my-profile",
"recipient_id": "34600111222",
"template": {
"name": "order_update",
"language": "en_US",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Jane" },
{ "type": "text", "text": "#1042" }
]
}
]
}
}'

Responses​

  • 200 OK
{
"success": true,
"platform": "whatsapp",
"recipient_id": "34600111222",
"message_id": "wamid.HBgLMzQ2MDAxMTEyMjIVAgARGBI5QTND...",
"messages": [
{ "message_id": "wamid.HBgLMzQ2MDAxMTEyMjIVAgARGBI5QTND...", "type": "text" }
]
}

messages has one entry per WhatsApp message sent (a text plus attachments can be several). message_id is the first one. "Accepted" means WhatsApp took the message; whether it was delivered and read shows up later in status in Get Conversations.

  • Errors

Errors carry an error_code you can branch on and, when WhatsApp gave one, its meta_error_code:

{
"success": false,
"error": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
"error_code": "whatsapp_template_required",
"meta_error_code": 131047
}
Statuserror_codeMeaning
400whatsapp_template_requiredMore than 24 hours since the person's last message. Send an approved template instead.
400dm_window_blockedThe window with this person is already known to be closed. Free text is refused until they write again (Retry-After header); templates still go through.
400whatsapp_invalid_recipientrecipient_id is not a phone number in international format.
400whatsapp_invalid_requestInvalid body: unknown attachment type, non-https URL, more than 10 attachments, text over 4096 characters, malformed template, location, contacts, buttons, list or cta_url, a limit exceeded (button title, 3 buttons, 10 list rows…), or attachments sent with an interactive message.
400whatsapp_not_connectedThe profile has no WhatsApp number connected.
400whatsapp_undeliverableWhatsApp could not deliver to that number (not on WhatsApp, outdated app, or the person blocked you).
400whatsapp_recipient_not_allowedYou are using a Meta test number and the recipient is not in its list of allowed numbers.
400whatsapp_api_errorAny other WhatsApp refusal; error and meta_error_code carry WhatsApp's reason.
401whatsapp_reauth_requiredThe connection to the number is no longer valid. Reconnect WhatsApp from the dashboard.
429dm_rate_limited, dm_send_in_progressToo many sends per minute, or another send to the same person is still running. Wait for Retry-After.
429—Daily DM limit of your account reached.
502whatsapp_unreachableWhatsApp did not answer. Retry later.

Get Conversations​

WhatsApp does not offer an API to read a number's past chats. Upload-Post keeps the messages it receives and sends from the moment you connect the number, for 90 days, and serves them here in the same shape as Instagram's conversations.

Endpoint​

GET /api/uploadposts/dms/conversations

Headers​

NameValueDescription
AuthorizationApikey your-api-key-hereYour API key for authentication

Query Parameters​

NameTypeRequiredDescription
platformStringYes"whatsapp".
userStringYesProfile username (as configured in Upload-Post).
limitIntegerNoConversations per page, 1 to 50. Default 20.
cursorStringNopagination.next_cursor from the previous page.
sinceStringNoOnly conversations with activity after this moment. Unix seconds, Unix milliseconds or an ISO 8601 date.
participant_idStringNoA phone number, to fetch only your chat with that person.
messages_limitIntegerNoLatest messages per conversation, 1 to 25. Default 10.

Conversations come newest first. Responses are cached for up to 60 seconds; sending a message clears the cache. To be told the moment a message arrives, subscribe to the dm_received webhook.

Example Request​

curl 'https://api.upload-post.com/api/uploadposts/dms/conversations?platform=whatsapp&user=my-profile&limit=10' \
-H 'Authorization: Apikey your-api-key-here'

Response​

  • 200 OK
{
"success": true,
"conversations": [
{
"id": "106540352242922:34600111222",
"updated_time": "2026-11-03T10:31:00+0000",
"window_open_until": "2026-11-04T10:30:00+0000",
"participants": {
"data": [
{ "id": "34600111222", "username": "34600111222", "name": "Jane" },
{ "id": "106540352242922", "is_me": true, "name": "Acme Store" }
]
},
"messages": {
"data": [
{
"id": "wamid.HBgLMzQ2MDAxMTEyMjIVAgARGBI5QTND...",
"created_time": "2026-11-03T10:31:00+0000",
"from": { "id": "106540352242922", "name": "Acme Store" },
"to": { "data": [{ "id": "34600111222", "name": "Jane" }] },
"message": "Hi Jane! Your order has shipped.",
"type": "text",
"direction": "out",
"status": "read"
},
{
"id": "wamid.HBgLMzQ2MDAxMTEyMjIVAgASGBQzQTk...",
"created_time": "2026-11-03T10:30:00+0000",
"from": { "id": "34600111222", "name": "Jane" },
"to": { "data": [{ "id": "106540352242922", "name": "Acme Store" }] },
"message": "Where is my order?",
"type": "image",
"direction": "in",
"attachments": [
{ "type": "image", "media_id": "1037543291543636", "mime_type": "image/jpeg", "caption": "Where is my order?" }
]
}
]
}
}
],
"pagination": { "next_cursor": "before_1793615400000", "has_more": true },
"account": {
"phone_number_id": "106540352242922",
"waba_id": "102290129340398",
"display_phone_number": "+34 600 999 888",
"verified_name": "Acme Store",
"quality_rating": "GREEN",
"messaging_limit_tier": "TIER_1K",
"connected_at": "2026-11-01T09:00:00+00:00"
}
}
FieldDescription
participantsThe other person (id = their phone number, name = their WhatsApp profile name when known) and your number (is_me: true).
window_open_untilUntil when you can send free text to this person. null when the 24-hour window is closed: send a template.
messages[].directionin (from the person) or out (from your number, including messages sent from the WhatsApp Business app on your phone).
messages[].typetext, image, video, audio, document, sticker, location, contacts, template, button, interactive… Reactions are not messages of their own.
messages[].messageThe text, the caption of a media message or the title of a tapped button.
messages[].reactionsReactions on this message: [{emoji, direction}], where direction is in (the person reacted) or out (you reacted).
messages[].contactsContact cards sent or received in a contacts message.
messages[].attachmentsReceived media come as {type, media_id, mime_type, caption, filename}: download them with Get Media. A location comes as {type, latitude, longitude, name, address}.
messages[].templateFor templates you sent: {name, language, components}.
messages[].statusOutgoing only: sent, delivered, read or failed. A failed message carries error: {code, title, message}.
messages[].reply_toId of the message this one quotes.
messages[].interactiveThe raw button or list reply when the person tapped an option (type interactive or button).
accountThe connected number: display number, verified name, quality rating and messaging limit tier.
paginationPass next_cursor as cursor to get the next page.

Templates​

Templates are messages approved in advance by WhatsApp. They are the only way to write to someone who has not messaged you in the last 24 hours. They live in your WhatsApp Business account; you can also manage them in Meta's WhatsApp Manager.

List templates​

GET /api/uploadposts/dms/templates?platform=whatsapp&user=my-profile
QueryDescription
userProfile username with the WhatsApp number. Required.
platformwhatsapp (the default; templates exist only on WhatsApp).
statusOptional filter: APPROVED, PENDING, REJECTED…
nameOptional filter by template name.
limit1 to 200. Default 100.
curl 'https://api.upload-post.com/api/uploadposts/dms/templates?platform=whatsapp&user=my-profile&status=APPROVED' \
-H 'Authorization: Apikey your-api-key-here'
{
"success": true,
"templates": [
{
"id": "1290654321987654",
"name": "order_update",
"status": "APPROVED",
"category": "UTILITY",
"language": "en_US",
"components": [
{ "type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped." }
]
}
]
}

Rejected templates also carry rejected_reason.

Create a template​

POST /api/uploadposts/dms/templates
FieldRequiredDescription
userYesProfile username with the WhatsApp number.
nameYesLowercase letters, numbers and underscores.
categoryNoUTILITY (default), MARKETING or AUTHENTICATION.
languageNoLanguage code. Default en_US.
bodyOne of body or componentsShortcut: the body text of the template. Use {{1}}, {{2}}… for variables.
examplesNoWith body: sample values for the variables, in order (["Jane", "#1042"]). Meta requires them; when missing, placeholders are sent.
header, footerNoWith body: a text header and footer (up to 60 characters each).
buttonsNoWith body: up to 10 buttons {text, url?} or {text, phone_number?}; a button with only text is a quick reply (text up to 25 characters).
componentsOne of body or componentsFull template in Meta's format (header, body, footer, buttons).
curl -X POST https://api.upload-post.com/api/uploadposts/dms/templates \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "whatsapp",
"user": "my-profile",
"name": "order_update",
"category": "UTILITY",
"language": "en_US",
"components": [
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} has shipped.",
"example": { "body_text": [["Jane", "#1042"]] }
}
]
}'
{
"success": true,
"template": { "id": "1290654321987654", "status": "PENDING", "category": "UTILITY" }
}

New templates start as PENDING while WhatsApp reviews them, usually within minutes. Only APPROVED templates can be sent.

Delete a template​

DELETE /api/uploadposts/dms/templates?platform=whatsapp&user=my-profile&name=order_update
curl -X DELETE 'https://api.upload-post.com/api/uploadposts/dms/templates?platform=whatsapp&user=my-profile&name=order_update' \
-H 'Authorization: Apikey your-api-key-here'

Returns {"success": true}. All languages of that template are deleted.

Template errors use the same error_code values as sending (whatsapp_invalid_request, whatsapp_reauth_required, whatsapp_api_error…).


Upload Media​

Upload a file once and send it with media_id, instead of hosting it at a public URL.

Endpoint​

POST /api/uploadposts/dms/media

Send it as multipart/form-data.

FieldRequiredDescription
platformYes"whatsapp" (or "facebook" for Messenger).
userYesProfile username with the WhatsApp number.
fileYesThe file.
typeNoimage, video, audio, document or sticker. Detected from the file when omitted. A file that does not fit a media type is sent as document.
curl -X POST https://api.upload-post.com/api/uploadposts/dms/media \
-H 'Authorization: Apikey your-api-key-here' \
-F 'platform=whatsapp' \
-F 'user=my-profile' \
-F '[email protected]'
{
"success": true,
"platform": "whatsapp",
"type": "image",
"media_id": "1037543291543636",
"mime_type": "image/jpeg",
"filename": "photo.jpg",
"size": 482113
}

Pass the media_id in attachments of Send a Message: {"type": "image", "media_id": "1037543291543636"}.

TypeFormatsMax size
imageJPEG, PNG5 MB
videoMP4, 3GPP16 MB
audioAAC, AMR, MPEG, MP4, OGG16 MB
documentAny file type100 MB
stickerWebP500 KB
Statuserror_codeMeaning
400whatsapp_invalid_requestMissing file or invalid type.
413whatsapp_media_too_largeThe file exceeds the limit for its type.
413dm_media_too_largeThe upload is larger than 100 MB.
400 / 502whatsapp_api_errorWhatsApp did not accept the file (the error field says why). 502 = retry later.

Get Media​

Media you receive on WhatsApp (photos, voice notes, documents…) come as a media_id, not a URL. This endpoint downloads the file. It also serves media you uploaded with Upload Media.

Endpoint​

GET /api/uploadposts/dms/media?platform=whatsapp&user=my-profile&media_id=1037543291543636
QueryDescription
userProfile username with the WhatsApp number. Required.
media_idThe media_id of an attachment from Get Conversations or the dm_received webhook. Required.
curl 'https://api.upload-post.com/api/uploadposts/dms/media?platform=whatsapp&user=my-profile&media_id=1037543291543636' \
-H 'Authorization: Apikey your-api-key-here' \
-o photo.jpg

The response is the file itself, with its Content-Type (for example image/jpeg or audio/ogg). Files up to 100 MB. WhatsApp keeps received media available for a limited time (around 30 days), so download what you need to keep.

Statuserror_codeMeaning
400whatsapp_invalid_requestMissing or malformed media_id.
404whatsapp_media_not_foundWhatsApp no longer has that media.
413whatsapp_media_too_largeThe file is larger than 100 MB.
502whatsapp_media_errorWhatsApp did not return the file. Retry later.

Receive messages in real time​

Subscribe to the dm_received webhook to get each incoming WhatsApp message as it arrives, with platform: "whatsapp", sender.id (the phone number), sender.name and the message.

Important Notes​

  1. Daily DM limits: WhatsApp messages count towards the same daily DM limit of your Upload-Post account as Instagram and Messenger DMs. When it is reached, the API returns 429.
  2. Message quality: WhatsApp watches how people react to your messages (blocks, reports). Keep templates relevant and only write to people who expect it; quality_rating in Get Conversations shows how WhatsApp rates your number.
  3. Only after connecting: messages exchanged before you connected the number are not available through the API.