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 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.
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
| Name | Value | Description |
|---|---|---|
| Authorization | Apikey your-api-key-here | Your API key for authentication |
Body Parameters (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
| platform | String | Yes | "whatsapp". |
| user | String | Yes | Profile username (as configured in Upload-Post) that has the WhatsApp number connected. |
| recipient_id | String | Yes | The 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). |
| message | String | Yes, unless attachments, template, location, contacts, reaction or sender_action is sent | Text, up to 4096 characters. Links get a preview. |
| attachments / attachment | Object or array | No | Up to 10 items {type, url} or {type, media_id}. See below. |
| template | Object | No | An approved template: {name, language, components}. When present, message and attachments are ignored. Works outside the 24-hour window. |
| reply_to | String | No | Id of a message in the chat (wamid...) to quote it in your reply. |
| location | Object | No | A location pin: {latitude, longitude, name?, address?}. If message is also sent, it goes first as a text message. |
| contacts | Array | No | 1 to 10 contact cards in Meta's contact format. Shortcuts are accepted: name can be a plain string and phones a plain string. |
| buttons | Array | No | Up to 3 reply buttons {id?, title} (title up to 20 characters). Needs message as the body (up to 1024 characters). |
| list | Object | No | A list menu: {button, sections}. See Interactive messages. Needs message as the body. |
| cta_url | Object | No | A call-to-action link button: {display_text, url}. Needs message as the body. |
| header | String | No | Interactive messages only: header text, up to 60 characters. |
| footer | String | No | Interactive messages only: footer text, up to 60 characters. |
| reaction | Object or String | No | React 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_id | String | With reaction or sender_action | The wamid of the incoming message to react to or mark as read. |
| sender_action | String | No | mark_read marks an incoming message as read (blue ticks). typing_on also shows the typing indicator. See Mark as read and typing. |
| typing | Boolean | No | With sender_action: "mark_read", also shows the typing indicator. |
Attachments
| Field | Description |
|---|---|
type | image, video, audio, document or sticker (file is accepted as document). |
url | Public https:// URL of the file. WhatsApp downloads it, so it must be reachable without login. |
media_id | Instead of url: a WhatsApp media id, either one you got from Upload Media or one received in an incoming message. |
caption | Optional, for image, video and document (max 1024 characters). |
filename | Optional, 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.
| Type | Fields |
|---|---|
buttons | Up 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
| Field | Description |
|---|---|
name | Template name, exactly as approved. |
language | Language code of the approved version, for example en_US or es. Default en_US. |
components | Optional. 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
}
| Status | error_code | Meaning |
|---|---|---|
| 400 | whatsapp_template_required | More than 24 hours since the person's last message. Send an approved template instead. |
| 400 | dm_window_blocked | The 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. |
| 400 | whatsapp_invalid_recipient | recipient_id is not a phone number in international format. |
| 400 | whatsapp_invalid_request | Invalid 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. |
| 400 | whatsapp_not_connected | The profile has no WhatsApp number connected. |
| 400 | whatsapp_undeliverable | WhatsApp could not deliver to that number (not on WhatsApp, outdated app, or the person blocked you). |
| 400 | whatsapp_recipient_not_allowed | You are using a Meta test number and the recipient is not in its list of allowed numbers. |
| 400 | whatsapp_api_error | Any other WhatsApp refusal; error and meta_error_code carry WhatsApp's reason. |
| 401 | whatsapp_reauth_required | The connection to the number is no longer valid. Reconnect WhatsApp from the dashboard. |
| 429 | dm_rate_limited, dm_send_in_progress | Too 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. |
| 502 | whatsapp_unreachable | WhatsApp 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
| Name | Value | Description |
|---|---|---|
| Authorization | Apikey your-api-key-here | Your API key for authentication |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| platform | String | Yes | "whatsapp". |
| user | String | Yes | Profile username (as configured in Upload-Post). |
| limit | Integer | No | Conversations per page, 1 to 50. Default 20. |
| cursor | String | No | pagination.next_cursor from the previous page. |
| since | String | No | Only conversations with activity after this moment. Unix seconds, Unix milliseconds or an ISO 8601 date. |
| participant_id | String | No | A phone number, to fetch only your chat with that person. |
| messages_limit | Integer | No | Latest 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"
}
}
| Field | Description |
|---|---|
participants | The other person (id = their phone number, name = their WhatsApp profile name when known) and your number (is_me: true). |
window_open_until | Until when you can send free text to this person. null when the 24-hour window is closed: send a template. |
messages[].direction | in (from the person) or out (from your number, including messages sent from the WhatsApp Business app on your phone). |
messages[].type | text, image, video, audio, document, sticker, location, contacts, template, button, interactive… Reactions are not messages of their own. |
messages[].message | The text, the caption of a media message or the title of a tapped button. |
messages[].reactions | Reactions on this message: [{emoji, direction}], where direction is in (the person reacted) or out (you reacted). |
messages[].contacts | Contact cards sent or received in a contacts message. |
messages[].attachments | Received 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[].template | For templates you sent: {name, language, components}. |
messages[].status | Outgoing only: sent, delivered, read or failed. A failed message carries error: {code, title, message}. |
messages[].reply_to | Id of the message this one quotes. |
messages[].interactive | The raw button or list reply when the person tapped an option (type interactive or button). |
account | The connected number: display number, verified name, quality rating and messaging limit tier. |
pagination | Pass 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
| Query | Description |
|---|---|
user | Profile username with the WhatsApp number. Required. |
platform | whatsapp (the default; templates exist only on WhatsApp). |
status | Optional filter: APPROVED, PENDING, REJECTED… |
name | Optional filter by template name. |
limit | 1 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
| Field | Required | Description |
|---|---|---|
user | Yes | Profile username with the WhatsApp number. |
name | Yes | Lowercase letters, numbers and underscores. |
category | No | UTILITY (default), MARKETING or AUTHENTICATION. |
language | No | Language code. Default en_US. |
body | One of body or components | Shortcut: the body text of the template. Use {{1}}, {{2}}… for variables. |
examples | No | With body: sample values for the variables, in order (["Jane", "#1042"]). Meta requires them; when missing, placeholders are sent. |
header, footer | No | With body: a text header and footer (up to 60 characters each). |
buttons | No | With 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). |
components | One of body or components | Full 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.
| Field | Required | Description |
|---|---|---|
platform | Yes | "whatsapp" (or "facebook" for Messenger). |
user | Yes | Profile username with the WhatsApp number. |
file | Yes | The file. |
type | No | image, 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"}.
| Type | Formats | Max size |
|---|---|---|
image | JPEG, PNG | 5 MB |
video | MP4, 3GPP | 16 MB |
audio | AAC, AMR, MPEG, MP4, OGG | 16 MB |
document | Any file type | 100 MB |
sticker | WebP | 500 KB |
| Status | error_code | Meaning |
|---|---|---|
| 400 | whatsapp_invalid_request | Missing file or invalid type. |
| 413 | whatsapp_media_too_large | The file exceeds the limit for its type. |
| 413 | dm_media_too_large | The upload is larger than 100 MB. |
| 400 / 502 | whatsapp_api_error | WhatsApp 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
| Query | Description |
|---|---|
user | Profile username with the WhatsApp number. Required. |
media_id | The 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.
| Status | error_code | Meaning |
|---|---|---|
| 400 | whatsapp_invalid_request | Missing or malformed media_id. |
| 404 | whatsapp_media_not_found | WhatsApp no longer has that media. |
| 413 | whatsapp_media_too_large | The file is larger than 100 MB. |
| 502 | whatsapp_media_error | WhatsApp 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
- 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. - Message quality: WhatsApp watches how people react to your messages (blocks, reports). Keep templates relevant and only write to people who expect it;
quality_ratingin Get Conversations shows how WhatsApp rates your number. - Only after connecting: messages exchanged before you connected the number are not available through the API.