Use Tab, then Enter to open a result.
WhatsApp Flows transform the user experience from static text exchanges to structured data entry. Capturing user input is only half of the requirement for enterprise applications. High-utility workflows often require an immediate document output like an invoice, a policy summary, or a booking confirmation. Generating these documents requires a robust link between the WhatsApp Flow frontend and a backend document engine.
Building a WhatsApp Flow dynamic PDF generation system involves coordinating between the Flow interactive UI and external webhook callbacks. This architecture must handle latency, ensure document security, and maintain session state across multiple API calls. This guide focuses on the engineering patterns required to build a resilient PDF generation pipeline.
The Architecture of Synchronous vs Asynchronous Generation
WhatsApp Flow endpoints impose a strict 10-second timeout. If your backend fails to respond within this window, the user sees a generic error message. PDF generation is a resource-intensive process. Converting HTML to PDF via headless browsers often takes between 2 and 5 seconds depending on complexity. While this fits within the 10-second window, it leaves little room for network jitter or database lookups.
A synchronous pattern involves generating the PDF and returning the media ID directly in the flow response. This works for simple documents but fails under high load. A more resilient approach uses an asynchronous pattern. The backend acknowledges the flow submission immediately. A background worker then generates the PDF and sends it to the user as a standalone media message. This decouples the UI interaction from the document processing logic.
Prerequisites for Document Automation
You need a WhatsApp Business API account or a developer-friendly alternative like WASender for testing session-based interactions. The infrastructure requires a publicly accessible HTTPS endpoint to receive callbacks. You also need a storage solution like Amazon S3 or Cloudflare R2 to host generated files before they are uploaded to WhatsApp servers.
The PDF engine is the core component. Puppeteer and Playwright are the industry standards for converting HTML templates into pixel-perfect PDFs. If you prefer a managed approach, services like Gotenberg provide a Docker-ready API for document conversion.
Implementing the WhatsApp Flow Schema
The flow must capture all data points required for the PDF. Use a data_exchange action to send this information to your server. The following JSON snippet demonstrates a simple flow structure for a service quote request.
{
"version": "3.1",
"screens": [
{
"id": "QUOTE_FORM",
"title": "Request a Quote",
"terminal": true,
"data": {
"service_types": [
{ "id": "standard", "title": "Standard Repair" },
{ "id": "premium", "title": "Premium Overhaul" }
]
},
"layout": {
"type": "SingleColumnLayout",
"children": [
{
"type": "Dropdown",
"label": "Service Type",
"name": "service_id",
"required": true,
"data_source": "service_types"
},
{
"type": "TextInput",
"label": "Full Name",
"name": "user_name",
"required": true
},
{
"type": "Footer",
"label": "Generate PDF Quote",
"on_click_action": {
"name": "data_exchange",
"payload": {
"user_name": "${form.user_name}",
"service_id": "${form.service_id}"
}
}
}
]
}
}
]
}
Handling the Webhook Callback
When the user clicks the footer button, Meta sends a POST request to your configured endpoint. Your server must verify the request signature to ensure it originated from Meta. After verification, extract the payload.
In a production environment, push this payload to a message queue like RabbitMQ or Redis. This keeps the initial response fast. If you choose the synchronous path for small files, your code handles the PDF generation before sending the final response to the Flow.
const express = require('express');
const puppeteer = require('puppeteer');
const app = express();
app.post('/whatsapp-flow-webhook', async (req, res) => {
const { user_name, service_id } = req.body.action_payload;
// 1. Send immediate response to Flow UI to avoid timeout
res.json({
version: "3.1",
screen: "QUOTE_FORM",
data: {
extension_message_response: {
params: {
status: "processing",
message: "Your quote is being generated."
}
}
}
});
// 2. Trigger asynchronous PDF generation
generateAndSendPDF(user_name, service_id, req.body.sender_id);
});
async function generateAndSendPDF(name, service, recipient) {
const browser = await puppeteer.launch();
const page = await browser.newPage();
const htmlContent = `<h1>Quote for ${name}</h1><p>Service: ${service}</p>`;
await page.setContent(htmlContent);
const pdfBuffer = await page.pdf({ format: 'A4' });
await browser.close();
// 3. Logic to upload to WhatsApp and send to recipient follows here
}
Media Upload and Message Delivery
WhatsApp does not allow sending a PDF as a raw binary in the message payload. You must first upload the file to the WhatsApp Media API. This returns a media_id.
For official Cloud API users, this involves a multipart POST request to the /media" endpoint. If you use WASender, you utilize the media upload endpoint provided in their documentation. Once you have the media_id`, send a document message to the user. Use the phone number captured from the webhook metadata as the recipient.
Managing Document Lifecycles and Storage
Storing every generated PDF indefinitely creates a storage bottleneck and a privacy risk. Implement a TTL (Time to Live) policy on your storage bucket. Most WhatsApp documents only need to exist long enough for the upload to complete.
If your business requirements mandate that users access these documents later, generate a signed URL from S3. Instead of sending a media_id, you send a template message with a button that links to the signed URL. This reduces the load on your WhatsApp API quota and provides a better experience for users on low-bandwidth connections.
Security and Signature Verification
Security is paramount when handling user data. Every callback from WhatsApp Flows is encrypted. You must use your App Secret to decrypt the payload. Failure to verify signatures allows attackers to spoof requests and trigger expensive PDF generation processes on your infrastructure.
Ensure your endpoint only accepts requests with a valid X-Hub-Signature-256 header. Use a library like crypto in Node.js to perform a constant-time string comparison between your calculated hash and the provided signature.
Troubleshooting Common Failures
Failures in this pipeline typically fall into three categories: timeouts, rendering errors, and upload rejections.
Timeout Errors
If your logs show 408 Request Timeout, your backend is taking too long to respond to the Flow. Move the PDF logic to a background worker. Ensure your initial response to the Flow is sent within 2 seconds to account for network overhead.
Rendering Errors
Puppeteer might fail if the HTML template contains external assets that take too long to load. Embed CSS and images as Base64 strings directly in the HTML template. This removes external dependencies and speeds up the rendering process.
Media Upload Failures
WhatsApp has specific requirements for PDF files. Ensure the file header is a valid PDF signature. If the upload fails with a 400 Bad Request, check if the file size exceeds the limits. While the limit is high, extremely large reports with many high-resolution images might trigger this.
Practical Examples of Use Cases
- Insurance Industry: A user completes a claim form via a Flow. The system generates a summary PDF with a claim number and sends it instantly.
- Real Estate: A Flow collects property preferences. The backend generates a personalized PDF catalog of available listings and delivers it to the user.
- E-commerce: After a bulk order inquiry, the system calculates tiered pricing and generates a formal pro-forma invoice.
FAQ
Do I need a dedicated server for PDF generation? Serverless functions like AWS Lambda or Google Cloud Functions are ideal for this. They scale automatically based on the number of incoming Flow submissions. However, ensure the function has enough memory to run a headless browser.
What is the maximum file size for WhatsApp PDFs? Documents sent through the WhatsApp Business API have a limit of 100MB. For optimal user experience, keep PDFs under 5MB so they download quickly on mobile devices.
Can I password-protect the generated PDFs?
Puppeteer does not natively support password protection. You must use a secondary library like qpdf or pdf-lib to encrypt the buffer before uploading it to WhatsApp.
How do I handle multi-language PDF generation?
Pass the language parameter from the Flow metadata to your backend. Use a templating engine like Handlebars or EJS to inject the correct translations into your HTML before the PDF engine renders it.
What happens if the media upload fails but the Flow is finished? Implement a retry mechanism in your background worker. If the media upload fails, the worker should retry with exponential backoff. If it still fails after multiple attempts, send a text message to the user explaining the delay or providing a web link to the document.
Is it possible to generate PDFs without a headless browser?
Yes. Libraries like PDFKit allow you to build PDFs programmatically. This is faster and uses fewer resources than a headless browser but makes complex layouts more difficult to design.
Scalability Considerations
As your volume grows, the PDF generation process will become a bottleneck. Horizontal scaling of your worker nodes is necessary. Monitor the CPU usage of your PDF engine. Headless browsers are CPU intensive. If you observe high latency, increase the number of concurrent workers or move to a specialized document generation service. This ensures that a spike in WhatsApp Flow traffic does not crash your primary application server.
Always use a unique identifier for every generation request. This prevents race conditions where one user might receive another user's document. Use UUIDs for filenames and ensure your storage paths are isolated per session.
By following this architectural pattern, you build a system that remains stable under load and provides a professional, automated experience for your WhatsApp users. Focus on the separation of concerns between the UI and the document engine to ensure long-term reliability."
