ignacioFinochietti/whatsapp-flows-botmaker-ai-prompt / botmaker-whatsapp-flows
botmaker-whatsapp-flows
VerifiedStrict architectural rules, UI constraints, and error prevention guidelines for building Meta WhatsApp Flows (Flow JSON) and Botmaker Action Code endpoints (data_exchange). Use when designing flows, writing action code endpoints, fixing 400 Decryption problems, schema validation errors, or DAG routing.
Development Guidelines: WhatsApp Flows & Botmaker Data Exchange
Strict architecture rules, Meta schema constraints, and error prevention runbooks for designing WhatsApp Flows and writing Botmaker Action Code (data_exchange) endpoints.
1. Golden Rules of Meta WhatsApp Flows (Frontend)
Schema & Versions
- Flow JSON Version: Always use
"version": "6.3"and"data_api_version": "3.0". Never use deprecated or frozen versions (1.0,2.0,3.0,3.1), as Meta's builder rejects them with"Flow JSON version is not supported". - Layout Architecture: Every screen MUST declare
"type": "SingleColumnLayout"with a single top-level"Form"container holding all interactive children and the footer. - Kebab-Case Enforcement: All component keys and properties MUST be strictly kebab-case (
on-click-action,data-source,input-type,helper-text). Using camelCase (onClickAction,dataSource) triggers schema validation rejection. - Mandatory
__example__: Every dynamic field declared in a screen'sdataschema MUST have a valid__example__. Omitting examples throws Meta's"property has no example"error. - Binding Syntax:
- Dynamic data from endpoint:
${data.property_name} - Form input value:
${form.input_name}
- Dynamic data from endpoint:
UX & Screen Flow Architecture
- [RULE - Zero Friction]: NEVER create intermediary screens that only contain informational text and a "Continue" button. Always combine instructional text with actionable inputs/selectors on the same screen.
- [RULE - Reactive In-Screen Visibility]: Prefer dynamic visibility (
visible: "${data.showSection}"andenabled: "${data.isEnabled}") over creating separate transition screens. The endpoint can show, hide, or enable components on the active screen in real-time viaflow.data. - [RULE - Expression Type Safety]: When writing expressions in conditional routing or visibility bindings (
If/Switch), operand data types MUST match identically (e.g., booleantruevs"true", number vs string). Type mismatches throwinvalid operand formatorType mismatch.
2. Routing Model & Navigation Contract (DAG)
Meta enforces a strict Directed Acyclic Graph (DAG) with forward-only routing:
"routing_model": {
"SCREEN_A": ["SCREEN_B", "SCREEN_C"],
"SCREEN_B": ["SCREEN_D"]
}
Critical Routing Rules:
- No Backward Routes / No Cycles:
- Meta strictly rejects backward routes that mirror forward routes:
Backward route [B->A] corresponding to forward route [A->B] is not allowed. - Returning to previous screens is handled natively by the
<(Back) arrow in WhatsApp's top-left app bar. Never declare backward routes or duplicate back buttons in data exchange.
- Meta strictly rejects backward routes that mirror forward routes:
- Terminal Screens:
- Screens with no forward progression (e.g.
CONFIRMATION,NO_RESULTS) MUST declare"terminal": true. - Terminal screens MUST NOT be keys in
routing_model(e.g. if the entire flow has only one terminal screen,"routing_model": {}). - Terminal screen footers MUST use
"name": "complete"(neverdata_exchange).
- Screens with no forward progression (e.g.
- Declared Destinations:
- Any
flow.nextScreenreturned by the server MUST be explicitly declared inrouting_model[currentScreen]. Undeclared targets trigger client-side runtime crashes.
- Any
- Explicit Cross-Screen State Propagation:
- WhatsApp Flows do NOT persist previous screen form state globally for the endpoint to inspect at any moment.
- Crucial selections or inputs from prior screens MUST be explicitly forwarded inside the
payloadof subsequentnavigateordata_exchangeactions (e.g.,{ "previousSelectionId": "${form.currentSelection}", "action": "NEXT_STEP" }).
3. Botmaker Action Code Endpoint (data_exchange)
Endpoint URL Structure
https://functions.botmaker.com/whatsapp-flows/:businessId/:wabaId/:actionCode
[!IMPORTANT]
:wabaIdMUST be the 15–16 digit Meta WhatsApp Business Account ID (WABA ID), NEVER the phone number. Placing a phone number causesEstado 400: Decryption problemat the Botmaker gateway before your script runs.
Production Boilerplate
// Injected globals in Botmaker VM:
// screen, data, flow, bmconsole, user, result
async function handleFlow() {
const currentScreen = typeof screen !== 'undefined' ? screen : null;
const currentData = (typeof data !== 'undefined' && data) ? data : {};
const action = currentData.action || currentData.component_action || null;
// 1. Health-check ping (Mandatory for Meta & Botmaker endpoint verification)
if (action === 'ping') {
flow.data = { status: 'active' };
flow.send();
return;
}
// 2. Initial Flow Launch / Reset
if (!currentScreen || action === 'iniciar' || action === 'INIT') {
flow.data = {};
flow.nextScreen = 'FIRST_SCREEN';
flow.send();
return;
}
// 3. Action Transitions
if (action === 'fetch_details') {
const selectedId = currentData.selectedId;
// Query API / Database...
flow.data = {
showDynamicMessage: true,
dynamicMessage: 'Details loaded successfully'
};
flow.send();
return;
}
// Default fallback
flow.send();
}
async function main() {
try {
await handleFlow();
} catch (error) {
if (typeof bmconsole !== 'undefined' && bmconsole.log) {
bmconsole.log('[Flow Error]: ' + error.message);
}
if (typeof user !== 'undefined' && user.set) {
user.set('error_flow', error.message || 'Unknown error');
}
if (typeof flow !== 'undefined' && flow.send) {
flow.data = {
showDynamicMessage: true,
dynamicMessage: 'An unexpected error occurred. Please try again.'
};
flow.send();
}
} finally {
// CRITICAL: Botmaker VM requires result.done() to release the sandbox
if (typeof result !== 'undefined' && result && typeof result.done === 'function') {
result.done();
}
}
}
main();
Critical Backend Architecture Rules:
- Lifecycle Termination (
flow.send()+result.done()):- Every
data_exchangeexecution path MUST populateflow.data(and optionallyflow.nextScreen) and callflow.send(). - The script execution MUST always trigger
result.done()inside afinallyblock. Missingresult.done()causes the Botmaker VM sandbox to hang until timeout.
- Every
- Context Access & Latency:
- Use injected globals (
user.get('var')/user.set('var', val)) for zero-latency session variables. - Avoid heavy external REST calls like
botmakerAPI.getChat()unless strictly required, as extra round-trips risk breaching WhatsApp's strict 2500ms latency SLA.
- Use injected globals (
- Graceful UI Fallbacks:
- If an external API or database returns empty results, inject explicit fallback flags into
flow.data(e.g.showSelector: false,emptyMessage: "No items available", empty array[]) or navigate to a declared terminal screen (NO_RESULTS). Never leave selectors unpopulated without fallback handling.
- If an external API or database returns empty results, inject explicit fallback flags into
- Input Sanitization ("Other" / Free Text):
- When offering a fallback selection (like
"OTHER") followed by a free-text input (TextInput), overwrite the generic ID with the user's sanitized text response before persisting to CRM or session variables.
- When offering a fallback selection (like
4. Component Patterns & Hard Limits
| Element | Max Limit | Consequence of Breach | Best Practice |
|---|---|---|---|
| Dropdown / Radio Title | 30 characters | Client screen crash / Validation error | Enforce title.substring(0, 30) or helper utility. |
| Description | 200 characters | Payload rejection | Enforce desc.substring(0, 200). |
| List / Dropdown Items | 200 items | Payload size / UI freeze | Enforce .slice(0, 200). |
| Payload Size | < 100 KB | WhatsApp Flow failure | Exclude large images and unnecessary metadata. |
| SLA Latency | < 2500 ms | Client timeout spinner | Use 2000ms timeouts on external HTTP requests. |
5. Pre-flight Verification Checklist
Before publishing any WhatsApp Flow or Botmaker endpoint:
- Flow JSON declares
"version": "6.3"and"data_api_version": "3.0". - All screens use
SingleColumnLayoutwith a single top-levelForm. - All component properties use strict kebab-case.
- All dynamic data keys declare a valid
__example__. - Routing model has NO backward route cycles.
- Terminal screens declare
"terminal": trueand are NOT keys inrouting_model. - Botmaker endpoint URL uses the numerical
wabaId(15–16 digits), NOT a phone number. - Action Code handles
action === 'ping'returning{ status: 'active' }. - Action Code always concludes with
result.done()in afinallyblock. - Option titles are clamped to $\le$ 30 characters and lists capped at $\le$ 200 items.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |