Document messages

Updated: Nov 3, 2025 Document messages are messages that display a document icon, linked to a document, that a WhatsApp user can tap to download.

Request syntax

Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages endpoint to send a document message to a WhatsApp user.

curl 'https://graph.facebook.com/&lt;API_VERSION&gt;/&lt;WHATSAPP_BUSINESS_PHONE_NUMBER_ID&gt;/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
\{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "&lt;WHATSAPP_USER_PHONE_NUMBER&gt;",
  "type": "document",
  "document": {
    "id": "&lt;MEDIA_ID&gt;", <!-- Only if using uploaded media -->
    "link": "&lt;MEDIA_URL&gt;", <!-- Only if using hosted media (not recommended) -->
    "caption": "&lt;MEDIA_CAPTION_TEXT&gt;",
    "filename": "&lt;MEDIA_FILENAME&gt;",
    "caption": "&lt;MEDIA_CAPTION_TEXT&gt;"
  }
}'

Request parameters

Placeholder	Description	Example Value
`<ACCESS_TOKEN>` String	Required. System token or business token.	`EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD`
`<API_VERSION>` String	Optional. Graph API version.	v24.0
`<MEDIA_CAPTION_TEXT>` String	Optional. Media asset caption text. Maximum 1024 characters.	`Lucky Shrub Invoice`
`<MEDIA_FILENAME>` String	Optional. Document filename, with extension. The WhatsApp client will use an appropriate file type icon based on the extension.	`lucky-shrub-invoice.pdf`
`<MEDIA_ID>` String	Required if using uploaded media, otherwise omit. ID of the uploaded media asset.	`1013859600285441`
`<MEDIA_URL>` String	Required if using hosted media, otherwise omit. URL of the media asset hosted on your public server. For better performance, we recommend using `id` and an uploaded media asset ID instead.	`https://www.luckyshrub.com/invoices/FmOzfD9cKf/lucky-shrub-invoice.pdf`
`<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>` String	Required. WhatsApp business phone number ID.	`106540352242922`
`<WHATSAPP_USER_PHONE_NUMBER>` String	Required. WhatsApp user phone number.	`+16505551234`

Supported document types

Document Type	Extension	MIME Type	Max Size
Text	.txt	text/plain	100 MB
Microsoft Excel	.xls	application/vnd.ms-excel	100 MB
Microsoft Excel	.xlsx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	100 MB
Microsoft Word	.doc	application/msword	100 MB
Microsoft Word	.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document	100 MB
Microsoft PowerPoint	.ppt	application/vnd.ms-powerpoint	100 MB
Microsoft PowerPoint	.pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation	100 MB
PDF	.pdf	application/pdf	100 MB

Example request

Example request to send a PDF in a document message with a caption to a WhatsApp user.

curl 'https://graph.facebook.com/v24.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
\{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "document",
  "document": {
    "id": "1376223850470843",
    "filename": "order_abc123.pdf",
    "caption": "Your order confirmation (PDF)"
  }
}'

Example response

\{
  "messaging_product": "whatsapp",
  "contacts": [\
    {\
      "input": "+16505551234",\
      "wa_id": "16505551234"\
    }\
  ],
  "messages": [\
    {\
      "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA"\
    }\
  ]
}

Did you find this page helpful? Thumbs up icon

ON THIS PAGE Request syntax Request parameters Supported document types Example request Example response

Overview

Getting started

Business setup

Messages

Templates

Embedded signup

Flows

Calling

Groups

Payments

Catalogs

Marketing messages

Click to WhatsApp ads

Solution providers

API reference

Pricing

Policies

Other

Support

Document messages

Document messages

Request syntax

Request parameters

Supported document types

Example request

Example response

​Document messages

​Request syntax

​Request parameters

​Supported document types

​Example request

​Example response

Document messages

Request syntax

Request parameters

Supported document types

Example request

Example response