This article shows how to build a Custom Tool in Frontline that sends a WhatsApp interactive list using the WhatsApp Cloud API. Lists are great for guided choices (e.g., select a plan, pick a time window, choose a department) with minimal typing.
Heads‑up: Interactive list messages are only available within the 24‑hour service window after the user’s last message. They’re not template messages. If you need to message outside the 24‑hour window, use a template instead.
⚙️ What you’ll need
Phone Number ID for your WhatsApp Business number (Cloud API).
A valid Access Token with permissions to send messages.
The recipient’s phone in E.164 format (e.g.,
+598...).
🚀 Step‑by‑step in Frontline
1) Create the Custom Tool
Go to Platform → Tools → Create Tool.
Name: Send WhatsApp List.
Tool type: Custom Tool.
When to use: e.g., offer options for department or product category.
2) Configure the API request
Method:
POSTURL:
https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messagesHeaders:
Authorization: Bearer {ACCESS_TOKEN}Content-Type: application/json
Request Body (example):
{ "messaging_product": "whatsapp", "to": "{phone}", "type": "interactive", "interactive": { "type": "list", "body": { "text": "Please choose an option" }, "footer": { "text": "You can change it later" }, "action": { "button": "View options", "sections": [ { "title": "Departments", "rows": [ { "id": "sales", "title": "Sales", "description": "Talk to our sales team" }, { "id": "support", "title": "Support", "description": "Get technical help" } ] }, { "title": "Other", "rows": [ { "id": "billing", "title": "Billing" } ] } ] } } }3) Add data inputs
Create inputs like phone so your Agent can fill them from the conversation.
4) Test and save
Use Test Response. If successful (200 OK), the user will receive the list. Click Save Tool.
🧠 How replies come back
When a user taps a row, WhatsApp sends an interactive reply with a list_reply payload (includes the selected row id and title). Map these values in your Intents/Flows to branch the conversation (e.g., if id = support → route to Support flow).
✅ Best practices
Keep row IDs stable and machine‑friendly (e.g.,
sales,support).Keep copy short and clear in body, button, and titles.
Use sections to group more than 10 options for faster scanning.
If the session may be stale, first send a quick prompt to re‑open the 24‑hour window before the list.
🔍 Troubleshooting
400 Bad Request: Check JSON shape (
interactive.type = list), button/sections present, and at least one row.401/403: Token invalid or lacks permission for your Phone Number ID.
Message not delivered: Confirm user is within 24h window and the phone number is valid (E.164).
Still have questions?
Reach out through the Help button in Frontline or contact your CSM for assistance.