1. Identify the stack — confirm provider package, database adapter, and flow entrypoints before writing code.
2. Type the callback signature correctly:

   • ctx: BotContext

     →

     { body, from, name, host, ...platform fields }

   • methods: BotMethods

     →

     { flowDynamic, gotoFlow, endFlow, fallBack, state, globalState, blacklist, provider, database, extensions }

3. Enforce flow-control semantics — these three MUST be

   return

   ed:

   • return gotoFlow(flow)

     ·

     return endFlow('msg')

     ·

     return fallBack('msg')

   • These MUST be

     await

     ed:

     await flowDynamic(...)

     ·

     await state.update(...)

     ·

     await globalState.update(...)

4. Prefer small, composable flows — one responsibility per flow file.
5. Keep secrets in env vars — never hardcode tokens, keys, or credentials.
6. After writing any flow, run through the UX Review Checklist below — simulate the conversation as the end-user and verify every item before considering the flow done.
7. Always validate lint before finishing — run

   eslint . --no-ignore

   and fix every error before delivering code.

• Use

  *bold*

  for product names, totals, section headers, and actions the user must take.
• Use

  _italic_

  for descriptions, hints, and secondary info.
• Use

  •

  (not

  -

  ) for list items — renders cleaner on mobile.
• Use

  ━━━━━━━

  (or

  ---

  ) as a visual divider between sections inside one bubble.
• Never use HTML tags (

  <b>

  ,

  <br>

  , etc.) — WhatsApp ignores them.
• Never use standard markdown (

  **bold**

  ,

  ## heading

  ) — not supported.

These rules apply to every flow. Violating them makes the bot feel like spam.

flowDynamic

addAnswer

flowDynamic(['a','b','c'])

addAnswer(['a','b','c'])

Always use

FlowDynamicMessage[]

with

.join('\n')

in

body

when calling

flowDynamic

. Never pass raw string arrays.

flowDynamic(['line1','line2','line3',...])

flowDynamic([{ body: ['line1','line2','line3'].join('\n'), delay: rnd() }])

delay: Math.floor(Math.random() * 800) + 500

flowDynamic([...items.map(...)])

flowDynamic([{ body: items.map(...).join('\n'), delay: rnd() }])

Simulates "typing..." or "recording..." before sending a message. Makes the bot feel human. Only available with

BaileysProvider

and

SherpaProvider

.

type WAPresence = 'unavailable' | 'available' | 'composing' | 'recording' | 'paused'
// composing = typing bubble   recording = audio bubble

• Always call

  sendPresenceUpdate('paused', ...)

  after sending — clears the indicator.
• Combine with

  rnd()

  delays: presence update → wait →

  flowDynamic

  → paused.
• Use

  composing

  for text replies,

  recording

  for audio context.
• Never use on non-Baileys/Sherpa providers — will throw at runtime.

• Flow not switching →

  return gotoFlow(...)

• Session not ending →

  return endFlow(...)

• Fallback not repeating →

  return fallBack(...)

• State not saved →

  await state.update(...)

• Idle not firing → add

  capture: true

  alongside

  idle

  (never check

  idleFallBack

  )
• EVENTS flow not triggering → verify provider maps the event payload to

  EVENTS.*

• Circular import crash → use dynamic

  await import()

  inside the callback (never

  require()

  )
• Language server shows "Cannot find module" on dynamic imports → check if a circular dep actually exists; if not, replace with static top-level

  import

• ESLint errors after changes → run

  eslint . --no-ignore

  and fix before finishing

• builderbot/func-prefix-endflow-flowdynamic

  error →

  flowDynamic

  and

  endFlow

  are in the same callback; split into two chained

  addAction

  :
  typescript

  .addAction(async (_, { flowDynamic }) => { await flowDynamic(lines) })
  .addAction(async (_, { endFlow }) => { return endFlow('bye') })

"type": "module"

"module": "ES2022"

• NEVER use

  require()

  — it is not available in ESM.
• Default: use static top-level imports. Dynamic imports cause TypeScript language server errors when no circular dependency exists.
• Before using

  await import()

  , draw the dependency graph. Dynamic import is only justified when flow A calls flow B and flow B calls flow A (a real cycle).

✅ Static (no cycle):  welcome → menu → order → payment
   import { orderFlow } from './order.flow'   ← top of file

✅ Dynamic (real cycle): welcome ↔ order
   const { orderFlow } = await import('./order.flow')  ← inside callback

import()

.addAction(async (ctx, { gotoFlow }) => {
    const { targetFlow } = await import('./target.flow')
    return gotoFlow(targetFlow)
})

• Code patterns (scaffold, capture, gotoFlow, media, idle, flowDynamic, fallBack, REST, EVENTS, UX patterns): patterns.md
• Provider configs, database configs, TypeScript types: providers.md