How can I send a PDF document using the WhatsApp API?

Yes, you can send a PDF file over WhatsApp. To do this, you must use a pre-approved WhatsApp message template from Meta that is configured with a document header, and pass the public URL of your PDF as the document header variable.

Messaging API v2 (recommended)

Use Notify with platforms: ["WHATS_APP"]. Put the template name in whatsapp.content_id and the PDF URL in whatsapp.header_variables, a JSON-stringified object keyed by header type. The recipient goes into hwids.list with the whatsapp: prefix.

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["WHATS_APP"],
      "hwids": { "list": ["whatsapp:+1234567890"] },
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "whatsapp": {
                "content_id": "your_meta_template_name",
                "language": "en_US",
                "header_variables": "{\"document\":\"https://example.com/file.pdf\"}"
              }
            }
          }
        }
      }
    }
  }'

See the payload reference for all WhatsApp fields and the migration guide if you are moving from v1.

Legacy request example (deprecated endpoint)

The legacy /createWhatsAppMessage endpoint is deprecated; new integrations should use v2.

{
  "request": {
    "application": "APP_CODE",
    "auth": "API_TOKEN",
    "notifications": [
      {
        "send_date": "now",
        "content_id": "your_meta_template_name",
        "header_variables": {
          "document": "https://example.com/file.pdf"
        },
        "devices": [
          "whatsapp:+1234567890"
        ]
      }
    ]
  }
}

Key points to remember

• content_id must be the name of a Meta-approved template that includes a document header.
• The PDF file must be hosted at a publicly accessible URL.
• Set language if your template locale is not the default en_US; it must match the locale approved in Meta.
• With the legacy endpoint, each request must contain only one WhatsApp number in the devices array.
• Make sure the WhatsApp platform is fully configured in your Pushwoosh project before sending messages.