Skip to main content

​
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

PlaceholderDescriptionExample Value
&lt;ACCESS_TOKEN&gt;
String		Required.
System token or business token.		EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD
&lt;API_VERSION&gt;
String		Optional.
Graph API version.		v24.0
&lt;MEDIA_CAPTION_TEXT&gt;
String		Optional.
Media asset caption text.
Maximum 1024 characters.		Lucky Shrub Invoice
&lt;MEDIA_FILENAME&gt;
String		Optional.
Document filename, with extension. The WhatsApp client will use an appropriate file type icon based on the extension.		lucky-shrub-invoice.pdf
&lt;MEDIA_ID&gt;
String		Required if using uploaded media, otherwise omit.
ID of the uploaded media asset.		1013859600285441
&lt;MEDIA_URL&gt;
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
&lt;WHATSAPP_BUSINESS_PHONE_NUMBER_ID&gt;
String		Required.
WhatsApp business phone number ID.		106540352242922
&lt;WHATSAPP_USER_PHONE_NUMBER&gt;
String		Required.
WhatsApp user phone number.		+16505551234

​
Supported document types

Document TypeExtensionMIME TypeMax Size
Text.txttext/plain100 MB
Microsoft Excel.xlsapplication/vnd.ms-excel100 MB
Microsoft Excel.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet100 MB
Microsoft Word.docapplication/msword100 MB
Microsoft Word.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document100 MB
Microsoft PowerPoint.pptapplication/vnd.ms-powerpoint100 MB
Microsoft PowerPoint.pptxapplication/vnd.openxmlformats-officedocument.presentationml.presentation100 MB
PDF.pdfapplication/pdf100 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 Thumbs down icon ON THIS PAGE Request syntax Request parameters Supported document types Example request Example response