> ## Documentation Index
> Fetch the complete documentation index at: https://botmesh.afaya.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

## Do I need to scan the QR every time?

**No.** The session is saved in `./sessions/`. You only scan the QR the first
time. If the session is invalidated (you deleted the folder or WhatsApp
unlinked the device), you'll need to scan again.

## Can I use the bot without scanning QR?

Yes, with a **pairing code** (Baileys transport):

```ts theme={null}
const bot = new Bot({
  provider: new BaileysProvider({
    session: 'my-bot',
    pairingPhoneNumber: '+57300XXXXXXX', // full international format
  }),
})

// The pairing code arrives on the 'qr' event (the same event that carries the QR string)
bot.on('qr', (code) => console.log('Type this code in WhatsApp > Linked devices:', code))
```

## Does the bot work in groups?

Yes. `when()` handlers work in groups by default. To respond only in private:

```ts theme={null}
bot.when('hi', async (ctx) => {
  if (ctx.isGroup) return
  await ctx.reply('👋')
})
```

In a group, each participant gets an **independent conversation** by
default when they trigger a flow — two people talking to the bot in the
same group don't share state. Set `conversationScope: 'chat'` if you want
one shared conversation per group instead.

## Why doesn't `bot.when('hi')` match "hi there"?

The default match strategy is **normalized equals**, not "contains" — the
message must equal the trigger exactly after lowercasing, stripping accents
and collapsing spaces. For substring matching, use a `TriggerObject`:

```ts theme={null}
bot.when({ pattern: 'hi', match: 'contains' }, handler)
```

`match` also accepts `'startsWith'` and `'endsWith'`.

## Can I send buttons?

It depends on the transport. With the official Cloud API (`@botmesh/meta`)
and Telegram, `ctx.buttons(text, buttons)` sends **native** buttons (see
[Messages & media](https://botmesh.afaya.com.co/guide/messages.md)). On Baileys, no — native interactive
buttons/lists are dead in the current WhatsApp Web protocol. Use a numbered
menu (`.choose()` in a flow, `c.choose()` in a conversation) or a real poll:

```ts theme={null}
await ctx.poll('Confirm your order?', ['Yes', 'No'])
```

## Do flows/conversations survive a restart?

Only if you opt in. `flow(...).persistent()` checkpoints the conversation
after each step, but the default `MemoryStore` lives in memory — a restart
loses those checkpoints unless the store is file-backed:

```ts theme={null}
const bot = new Bot({
  provider: new BaileysProvider({ session: 'my-bot' }),
  store: new MemoryStore({ file: './store.json' }), // or use @botmesh/sqlite-store
})
```

## Can I send messages without someone writing first?

Yes, with `bot.send`:

```ts theme={null}
bot.schedule('0 9 * * *', async () => {
  await bot.send('57300XXXXXXX@s.whatsapp.net', '🌅 Good morning!')
})
```

To send one message to many chats use [`bot.broadcast()`](https://botmesh.afaya.com.co/guide/messages#broadcasts)
(batches, retries on rate limits, cancellable); to start a whole flow for
someone use [`bot.trigger()`](https://botmesh.afaya.com.co/guide/messages#starting-a-flow-programmatically).
On the WhatsApp Cloud API, free-form messages only go out inside the 24-hour
window: see [Session window](https://botmesh.afaya.com.co/guide/session-window.md).

## How do I stop the bot properly?

```ts theme={null}
process.on('SIGINT', async () => {
  console.log('🛑 Shutting down...')
  await bot.stop({ drain: true }) // wait for in-flight and paced replies (up to `timeout`, 10 s by default)
  process.exit(0)
})
```

## Can I have multiple bots in the same process?

Yes, with different providers/sessions:

```ts theme={null}
const bot1 = new Bot({ provider: new BaileysProvider({ session: 'bot-1' }) })
const bot2 = new Bot({ provider: new BaileysProvider({ session: 'bot-2' }) })
await bot1.start()
await bot2.start()
```

You can even mix transports — one `Bot` per provider
(e.g. a Baileys bot and a `CloudAPIProvider` bot in the same process).

## Does it work with WhatsApp Business?

Yes. The bot works with both personal and WhatsApp Business accounts.

## Can I build a ChatGPT-style AI assistant on WhatsApp?

Not on the WhatsApp Business Platform. Since **2026-01-15** Meta's terms
prohibit **general-purpose AI assistants** (open-ended chatbots whose main
purpose is the AI itself). AI that serves your business — customer support,
sales, bookings — is allowed. With `@botmesh/ai`, write a persona scoped to
your business; see the [AI plugin guide](https://botmesh.afaya.com.co/guide/ai.md#whatsapp-ai-policy-since-2026-01-15).

## Can my account get banned?

WhatsApp can detect excessive automation. To minimize risk:

* Don't send spam or mass messages
* Use `markOnlineOnConnect: false` (a `BaileysProvider` option)
* Respect rate limits (the provider's [built-in limiter](https://botmesh.afaya.com.co/guide/rate-limiting.md))
* Don't reply instantly to everything (turn on the [typing indicator](https://botmesh.afaya.com.co/guide/messages.md#typing-indicator-and-reply-delays) with `BotConfig.typing`)
* Consider the official [Cloud API](https://github.com/andresayac/botmesh/tree/main/packages/meta-provider) (`@botmesh/meta`) for business-critical bots — no ban risk

## Do I need TypeScript?

**No.** All examples work in plain JavaScript — just note the package is
**ESM-only**, so your project needs `"type": "module"` in `package.json`
(or a `.mjs` file) regardless of whether you use TypeScript. TypeScript
gives you autocomplete and type-checking, but it's optional.

## Why do I get `ERR_REQUIRE_ESM` or "require is not defined"?

You're trying to `require('@botmesh/core')` (or a transport package) from a
CommonJS file. There is no CJS build: switch to `import` (add
`"type": "module"` to your `package.json`, or use a `.mjs` extension).
More install errors (pnpm build scripts, native modules) are in
[Troubleshooting](https://botmesh.afaya.com.co/guide/troubleshooting.md#installing).

## Where is the full API reference?

At the [API Reference](https://botmesh.afaya.com.co/api/core.md), generated with TypeDoc from the source code and
grouped by topic (Bot, Messages & context, Flows, Store, Errors…). It covers the
three semver-covered entries of **`@botmesh/core`**: the main entry, `/spi` (for
authors of stores, backends and transports) and `/testing`.
`@botmesh/core/internal` is not documented on purpose: it has no semver guarantee.
The channel, store and plugin packages are documented in their guide pages and in
each package's README on npm.

## Still having problems?

* [Troubleshooting](https://botmesh.afaya.com.co/guide/troubleshooting.md): the common errors and their fixes
* [Open an issue on GitHub](https://github.com/andresayac/botmesh/issues)
* [Check the examples](https://botmesh.afaya.com.co/examples.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.