Builderbot Code Skill

BuilderBot Code Skill

Operate

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 returned:
   • return gotoFlow(flow) · return endFlow('msg') · return fallBack('msg')
   • These MUST be awaited: 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.

Critical Rules (common bugs)

Flow Chain

addKeyword(keywords, options?)        // ActionPropertiesKeyword: capture, idle, media, delay, regex, sensitive  ← NEVER use `buttons`
  .addAnswer(message, options?, cb?, childFlows?)
  .addAction(cb)
// cb: async (ctx: BotContext, methods: BotMethods) => void

State Quick Reference

// Per-user
await state.update({ key: value })
state.get('key')            // dot notation supported: 'user.profile.name'
state.getMyState()
state.clear()

// Global (shared across all users)
await globalState.update({ key: value })
globalState.get('key')
globalState.getAllState()

UX Review Checklist

After building any flow, mentally walk through the conversation as the end-user and verify every point below. Fix anything that fails before delivering the code.

WhatsApp Text Formatting

WhatsApp uses its own markdown — always apply it in message strings.

Rules

• 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.

Example — well-formatted bubble

const body = [
    '*🍕 Tu pedido*',
    '━━━━━━━━━━━━━━',
    `• Pizza: *Pepperoni*`,
    `• Tamaño: *Mediana (30 cm)*`,
    `• Cantidad: *2*`,
    '',
    `💰 Total: *$26 USD*`,
    '',
    '_Responde *sí* para confirmar o *no* para cancelar._',
].join('\n')

WhatsApp Messaging Norms

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

Critical distinction — flowDynamic vs addAnswer with arrays:

Always use FlowDynamicMessage[] with .join('\n') in body when calling flowDynamic. Never pass raw string arrays.

Random delay helper (define once per file)

const rnd = () => Math.floor(Math.random() * 800) + 500

Correct pattern — 3 bubbles max

await flowDynamic([
    {
        body: [
            '*Título*',
            '',
            items.map(i => `• ${i.name} — $${i.price}`).join('\n'),
        ].join('\n'),
        delay: rnd(),
    },
    {
        body: '*Sección 2*\nLínea A\nLínea B',
        delay: rnd(),
    },
])
// addAnswer o addAction siguiente = bubble 3

Presence Update (Baileys / Sherpa only)

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

Pattern — typing indicator before each message

const waitT = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))

.addAction(async (ctx, { provider, flowDynamic }) => {
    await provider.vendor.sendPresenceUpdate('composing', ctx.key.remoteJid)
    await waitT(1500)
    await flowDynamic([{ body: 'Mensaje que parece escrito por humano', delay: rnd() }])
    await provider.vendor.sendPresenceUpdate('paused', ctx.key.remoteJid)
})

Rules

• 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.

Debug Checklist

• 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:

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

Module System

This project uses ESM ("type": "module" in package.json, "module": "ES2022" in tsconfig).

• 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

When flows reference each other (circular), use dynamic import() inside the callback:

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

Modular Structure (recommended)

Organize flows in a src/flows/ directory with a barrel index.ts that exports the assembled flow:

src/
├── app.ts
├── flows/
│   ├── index.ts            # createFlow([...all flows])
│   ├── welcome.flow.ts
│   └── order.flow.ts
└── services/

// src/flows/index.ts
import { createFlow } from '@builderbot/bot'
import { welcomeFlow } from './welcome.flow'
import { orderFlow } from './order.flow'

export const flow = createFlow([welcomeFlow, orderFlow])

// src/app.ts
import { createBot, createProvider } from '@builderbot/bot'
import { MemoryDB as Database } from '@builderbot/bot'
import { BaileysProvider as Provider } from '@builderbot/provider-baileys'
import { flow } from './flows'

const main = async () => {
    const provider = createProvider(Provider)
    const database = new Database()
    await createBot({ flow, provider, database })
    provider.initHttpServer(+(process.env.PORT ?? 3008))
}
main()

References

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