Send a document message

Sends a file such as an invoice, ticket or report. Needs an open 24-hour window. Give the file as a public link or as an id from POST /v1/media/upload.

Tip

To send a document to someone outside the 24-hour window, for example an invoice the customer didn’t ask for, use a template with a document header instead.

Example

curl -X POST "$HELLO_API_URL/v1/<your-phone-number-id>/messages" \
  -H "Authorization: Bearer $HELLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919999999999",
    "type": "document",
    "document": {
      "link": "https://example.com/invoices/INV-2291.pdf",
      "filename": "Invoice INV-2291.pdf",
      "caption": "Your invoice for September"
    }
  }'

By media ID:

{
  "to": "+919999999999",
  "type": "document",
  "document": { "id": "1099999999993456", "filename": "Boarding pass.pdf" }
}

Response

202 Accepted (queued), or 200 with ?sync=true once WhatsApp accepts it. See Send a message.

Fields

Field	Type	Required	Description
document.link	string	One of link / id	Public HTTPS URL of the file
document.id	string	One of link / id	media_id from /v1/media/upload. Takes precedence if both are set.
document.filename	string	No	File name shown to the recipient, including the extension
document.caption	string	No	Text shown under the document

Supported formats: PDF, plain text, and Microsoft Word, Excel and PowerPoint (both .doc/.xls/.ppt and .docx/.xlsx/.pptx), up to 100 MB. See supported media.

Common errors

Status	code	Cause
403	OUTSIDE_24H_WINDOW	The recipient’s 24-hour window is closed
400	VALIDATION_ERROR	document is missing or the wrong shape
422	SEND_FAILED	(?sync=true only) WhatsApp rejected the send