Skip to main content
A document message sends a file attachment — PDF, Word, Excel, PowerPoint, or plain text — to a recipient. The file can be provided as a public URL or as a media ID from a prior upload. A filename field controls what name the recipient sees, and an optional caption adds text below the document. See Media by URL vs Media ID for when to use URL vs ID.

​
Send by URL

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "919959623255",
  "type": "document",
  "document": {
    "link": "https://example.com/Python%20Programming.pdf",
    "caption": "Here is your resume",
    "filename": "rahul_resume.pdf"
  }
}

​
Send by Media ID

Upload the file first (see Media by URL vs Media ID), then use the returned ID: 
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "919959623255",
  "type": "document",
  "document": {
    "id": "2252229765183486",
    "caption": "Here is your resume",
    "filename": "rahul_resume.pdf"
  }
}
When sending by ID, use id — not link. These are two separate fields; mixing them up causes the send to fail.

​
Fields

FieldRequiredDescription
linkif no idPublic https:// URL to the file
idif no linkMedia ID from a prior upload
filenamenoThe filename displayed to the recipient. Defaults to the original filename if omitted. Always set this to give the recipient a meaningful name.
captionnoPlain text shown below the document, max 1024 characters

​
Supported document types

TypeExtensionMIME typeMax size
PDF.pdfapplication/pdf100 MB
Microsoft Word.docapplication/msword100 MB
Microsoft Word.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document100 MB
Microsoft Excel.xlsapplication/vnd.ms-excel100 MB
Microsoft Excel.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet100 MB
Microsoft PowerPoint.pptapplication/vnd.ms-powerpoint100 MB
Microsoft PowerPoint.pptxapplication/vnd.openxmlformats-officedocument.presentationml.presentation100 MB
Plain text.txttext/plain100 MB
All document types support up to 100 MB.

​
Reference images

Document message by URL
Document message by media ID
Document received

​
Frequently asked

Set type to "document" and provide either a public URL in document.link or a media ID in document.id. Set document.filename to give the file a meaningful name for the recipient.
PDF, Word (.doc/.docx), Excel (.xls/.xlsx), PowerPoint (.ppt/.pptx), and plain text (.txt). All support up to 100 MB.
Use the filename field in the document object. For example, "filename": "June_Invoice.pdf". If you omit it, WhatsApp uses the original filename from the URL or upload.
Yes — use the caption field. It appears as text below the document in the chat, up to 1024 characters.
Check: (1) the file type is in the supported list above, (2) the file is under 100 MB, (3) if using a URL it is public https:// with no auth, (4) you used id (not link) when sending by media ID.

​
Gotchas & common mistakes

  • Using link instead of id — when sending by media ID, the field is id, not link.
  • No filename set — without a filename the recipient sees an unhelpful auto-generated name. Always set filename to something meaningful.
  • Unsupported file type — only the formats in the table above are supported. ZIP, CSV, and other types are not accepted as document messages.
  • File over 100 MB — exceeding it causes the send to fail. Compress or split large files.
  • http:// URL — must be https://. Plain HTTP is rejected.