Use Tab, then Enter to open a result.
WhatsApp Flows provide a structured way for users to interact with your business. When you build a product browser, you often face a major technical hurdle. WhatsApp limits the size of the data payload sent to a Flow. If your product catalog contains hundreds or thousands of items, you cannot load them all at once.
This article explains how to implement WhatsApp Flow pagination for large catalogs. You will learn to use dynamic webhook payloads to fetch data in small, manageable chunks. This approach ensures your Flow remains fast and responsive while giving users access to your entire inventory.
The Problem with Large Catalog Data
WhatsApp Flows have a strict data limit of 64KB for the entire state. If you try to send a list of 100 products with images and descriptions, you will hit this limit quickly. When the payload exceeds this size, the Flow fails to load. The user sees an error message and the interaction stops.
Loading too much data at once also increases latency. Users on slower mobile networks will wait several seconds for the screen to render. This leads to high drop-off rates.
Pagination solves these issues by breaking the catalog into pages. Instead of fetching 500 items, you fetch 10 items at a time. As the user clicks a Next button, the Flow makes a request to your server for the next set of data.
Prerequisites for Dynamic Pagination
Before you start the implementation, ensure you have the following components ready.
- A WhatsApp Business API account or a developer-friendly alternative like WASenderApi. WASenderApi allows you to test these flows using a standard WhatsApp session via QR code, which simplifies the early development phase for small teams.
- A backend server capable of receiving POST requests from WhatsApp webhooks. This server must handle JSON payloads and return a specific response structure.
- A database containing your product catalog. Each item should have a unique ID, a name, a price, and optionally a thumbnail URL.
- Basic knowledge of the WhatsApp Flow JSON schema and how to define screens.
Step 1: Define the Data API in the Flow JSON
The first step involves configuring your Flow to talk to an external server. You do this by defining a data_api in your Flow JSON. This endpoint serves as the bridge between the WhatsApp interface and your product database.
In your Flow definition, locate the screen where the product list appears. You must add an on-enter action or a button action that triggers a data_exchange request.
{
"version": "3.0",
"screens": [
{
"id": "PRODUCT_LIST",
"title": "Our Catalog",
"terminal": false,
"data": {
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"title": { "type": "string" },
"description": { "type": "string" }
}
/ }
},
"offset": { "type": "number" }
},
"layout": [
{
"type": "TextItem",
"text": "Select a product from the list below:"
},
{
"type": "List",
"datasource": "${data.products}",
"name": "selected_product"
},
{
"type": "Footer",
"label": "Next Page",
"on-click-action": {
"name": "data_exchange",
"payload": {
"action": "fetch_next_page",
"current_offset": "${data.offset}"
}
}
}
]
}
]
}
Step 2: Set Up the Webhook Backend
Your backend receives a JSON payload when the user clicks the Next Page button. This payload contains the current_offset. Your logic uses this value to determine which slice of the database to return.
For example, if your limit is 10 and the current_offset is 0, your server returns items 1 through 10. For the next request, the current_offset becomes 10, and you return items 11 through 20.
Here is a Node.js example using a simple Express server to handle the pagination logic.
const express = require('express');
const app = express();
app.use(express.json());
const catalog = [
/* Assume this is an array of 100 products */
];
app.post('/whatsapp-flow-webhook', (req, res) => {
const { action, payload } = req.body;
if (action === 'fetch_next_page') {
const offset = payload.current_offset || 0;
const limit = 10;
const nextOffset = offset + limit;
const products = catalog.slice(offset, nextOffset).map(p => ({
id: p.id.toString(),
title: p.name,
description: `$${p.price}`
}));
return res.json({
version: "3.0",
screen: "PRODUCT_LIST",
data: {
products: products,
offset: nextOffset
}
});
}
res.status(400).send('Invalid action');
});
app.listen(3000, () => console.log('Server running on port 3000'));
Step 3: Managing State Transitions
When the webhook returns the new data, the WhatsApp Flow updates the screen automatically. The key is to keep the offset state synchronized. Each time the user fetches a new page, the server must return the updated offset value so the next button click sends the correct pointer back to the server.
If you use WASenderApi to manage the session, the webhook interaction follows a similar pattern. Ensure your server correctly signs the response if you use official Meta requirements, or follow the session-specific headers if using an alternative gateway.
Practical Example: Search and Filter Pagination
Pagination often combines with search queries. If a user searches for "shoes", you need to paginate through only the matching results. In this case, your data_exchange payload must include the search term.
Your backend query changes from a simple slice to a filtered query:
- Receive
search_termandoffsetfrom the Flow. - Query the database:
SELECT * FROM products WHERE name LIKE %search_term% LIMIT 10 OFFSET 10. - Return the results and the new offset.
This approach prevents the user from scrolling through thousands of irrelevant items. It keeps the interaction focused and the payload small.
Edge Cases to Consider
Implementing pagination requires handling scenarios where the data does not exist or the process fails.
End of the Catalog
What happens when the user reaches the last item? Your backend must identify that no more items remain. You can send a flag like is_last_page: true. In your Flow JSON, use this flag to hide the Next Page button or change its label to "No more products".
Empty Results
If a search query returns zero items, do not return an empty list without context. Return a data object that triggers a specific message on the screen, such as "No products found. Please try a different search."
Network Latency
Since each page fetch requires a round trip to your server, users might experience a delay. Use the built-in loading states in WhatsApp Flows. When a data_exchange action triggers, the Flow shows a loading spinner automatically. Ensure your server responds within the 10-second timeout window imposed by WhatsApp.
Troubleshooting Common Issues
If your pagination fails, check these common error sources.
- Incorrect Version Number: Ensure the
versionin your webhook response matches the version in your Flow JSON. If they differ, the Flow will crash. - Payload Size: Even with 10 items, if your descriptions are extremely long, you might still hit the 64KB limit. Trim descriptions on the server side before sending them to the Flow.
- Integer vs String: WhatsApp Flows are strict about data types. If the schema expects a string for an ID, do not send an integer. Cast all values to the correct type in your backend.
- SSL and Security: WhatsApp requires a valid HTTPS connection for webhooks. If you use a self-signed certificate, the request will fail without a specific error message in the Flow debugger.
Frequently Asked Questions
What is the maximum number of items I should show per page?
Displaying 10 to 15 items per page provides a good balance between information density and performance. More items increase the risk of payload errors and make the list harder to navigate on small screens.
Do I need a separate endpoint for every screen in my Flow?
No. You use a single webhook endpoint and differentiate the logic using the action field in the payload. This keeps your backend code organized and easier to maintain.
Can I use cursor-based pagination instead of offset-based pagination?
Yes. Cursor-based pagination is often more efficient for large datasets that change frequently. Instead of an offset number, your server returns a unique identifier for the last item in the list. The Flow sends this ID back in the next request.
Does WASenderApi support these dynamic data exchanges?
Yes. While WASenderApi is an unofficial alternative, it supports standard webhook integrations. You can point the session to your backend to handle these flows. This is a practical choice for developers building internal tools or prototypes where official API onboarding is too slow.
How do I handle back-button navigation with pagination?
WhatsApp Flows manage the screen stack. If a user goes back, they return to the previous screen state. If you need to maintain the exact page they were on, you must store the state in the Flow data structure. Usually, the Flow handles the visual regression, but you may need to re-fetch data if you move between different functional screens.
Next Steps for Your Integration
Once you successfully implement basic pagination, you can add more advanced features. Try adding category filters that update the list dynamically. You could also implement a detailed view where clicking an item in the paginated list opens a new screen with more information about that specific product.
Start with a simple list of 10 items. Get the webhook communication working. Then, gradually introduce the offset logic and error handling. This step-by-step approach ensures you build a robust system that scales with your catalog size.
