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