Interactive & Template Messages
Relevant source files
The following files were used as context for generating this wiki page:
Interactive and Template messages provide a structured way for users to interact with automated systems via defined UI elements such as buttons, lists, and carousels. These message types transition away from plain text interactions toward rich graphical interfaces that include call-to-action (CTA) buttons, quick replies, and multi-option selection menus.
The system handles both "Native Flow" messages, which use a newer JSON-based parameterization for buttons, and legacy "Hydrated" template messages. These structures are managed through utility classes and composers that translate high-level JavaScript objects into the binary protocol formats required by the WhatsApp server.
Sources: lib/Utils/messages.js:632-680, lib/Utils/interactive-message.js:1-10
Interactive Message Types
The library supports several interactive message formats, primarily categorized by their visual presentation and interaction logic.
Button Messages
Button messages consist of a body, optional header (text, image, video, or document), optional footer, and up to three response buttons. These are often used for simple "Yes/No" or choice-based workflows.
Sources: lib/Utils/interactive-message.js:7-38, lib/Utils/messages.js:847-897
List Messages
List messages allow users to select from a menu of options organized into sections. They are characterized by a single "Button Text" that opens a vertical menu containing multiple rows.
Sources: lib/Utils/interactive-message.js:41-58, lib/Utils/messages.js:809-824
Native Flow Messages
Native Flow messages are the modern implementation of interactivity, where button behavior is defined by a name and a buttonParamsJson string. This allows for complex actions like opening URLs, copying text, or triggering location sharing.
Sources: lib/Utils/messages.js:632-680, lib/Utils/interactive-message.js:111-133
The following diagram illustrates the high-level flow of generating an interactive message:
The diagram shows the decision path based on the input message structure, leading to the final protocol buffer generation.
Sources: lib/Utils/messages.js:789-918, assets/buttonsbuilder/MessageBuilder.js:467-485
Template Message System
The Template system allows for predefined message structures with variable placeholders. These can be "Hydrated" (containing the full UI definition) or managed via a TemplateManager.
Template Variable Rendering
Templates use the {{variable:defaultValue}} syntax. The TemplateManager extracts these variables and provides a rendering engine to populate them with data.
Sources: lib/Utils/templates.js:18-41, lib/Utils/templates.js:93-104
Preset Templates
The system includes several preset categories:
- Order Management: Confirmation and Shipping notifications.
- Notifications: Reminders and Appointment confirmations.
- Support: Ticket creation and resolution alerts.
- Greetings: Welcome messages and Birthday wishes.
Sources: lib/Utils/templates.js:146-218
| Template Category | Purpose | Required Variables (Example) |
|---|---|---|
ORDER_CONFIRMATION | Transactional receipt | orderId, total |
WELCOME | User onboarding | name, companyName |
SUPPORT_TICKET | Customer service | ticketId, priority |
REMINDER | Event alerts | subject, date, time |
Sources: lib/Utils/templates.js:147-210
Native Flow Button Logic
Native flow buttons are defined by specific action names. The system maps shorthand fields to these names and their corresponding JSON parameters.
Action Mapping
| Shorthand Field | Native Flow Action Name | Purpose |
|---|---|---|
id | quick_reply | Sends a message back with the defined ID |
url | cta_url | Opens a web browser; supports useWebview |
copy | cta_copy | Copies the copy_code to the user's clipboard |
call | cta_call | Initiates a phone call to the defined number |
sections | single_select | Opens a selection list |
Sources: lib/Utils/messages.js:632-680, lib/Utils/interactive-message.js:111-177
Implementation Example: Copy Button
The generateCopyCodeButton utility creates a button that copies a code to the clipboard when pressed.
const generateCopyCodeButton = (body, copyCode, displayText = 'Copy Code', options) => {
return generateNativeFlowMessage(
body,
[{
name: 'cta_copy',
buttonParamsJson: JSON.stringify({
display_text: displayText,
copy_code: copyCode
})
}],
options
)
}
Sources: lib/Utils/interactive-message.js:135-147
Carousel Messages
Carousel messages allow for a horizontal scrollable list of "Cards." Each card must contain a media attachment (image, video, or product) along with its own interactive buttons.
Card Architecture
Each card in a carousel is an instance of an InteractiveMessage. The CarouselMessage container holds an array of these card definitions.
The class diagram shows the hierarchical relationship where a Carousel message acts as a container for multiple interactive card objects.
Sources: lib/Utils/messages.js:1012-1033, assets/buttonsbuilder/MessageBuilder.js:586-621
Rich Content & Code Highlights
Interactive messages can also include rich content types, specifically within the context of AI-forwarded responses. This includes tables and syntax-highlighted code blocks.
Tokenization Process
For code messages, the tokenizeCode function splits the input string into blocks tagged with specific highlight types (Keywords, Methods, Strings, Comments).
Sources: lib/Utils/message-composer.js:77-128, lib/Utils/rich-message-utils.js:15-46
Data Flow for Rich Messages
This sequence shows how raw code is transformed into a rich response via the tokenizer and composer utilities.
Sources: lib/Utils/message-composer.js:235-257, lib/Utils/rich-message-utils.js:220-250
Conclusion
Interactive and Template messages in this repository provide a robust framework for building non-linear chat experiences. By leveraging utility functions like prepareNativeFlowButtons and classes such as Button or Carousel builders, developers can create sophisticated UIs. The integration of a template variable system and a code tokenizer further enhances the ability to send dynamic, technical content through the WhatsApp protocol.
Sources: lib/Utils/messages.js:1145-1150, assets/buttonsbuilder/MessageBuilder.js:1-10