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

# Preguntas frecuentes

## ¿Necesito escanear el QR cada vez que inicio el bot?

**No.** La sesión se guarda en `./sessions/`. Solo escaneas el QR la
primera vez. Si la sesión se invalida (borraste la carpeta o WhatsApp
desvinculó el dispositivo), necesitarás escanear de nuevo.

## ¿Puedo usar el bot sin escanear el QR?

Sí, con **pairing code** (transporte Baileys):

```ts theme={null}
const bot = new Bot({
  provider: new BaileysProvider({
    session: 'mi-bot',
    pairingPhoneNumber: '+57300XXXXXXX', // formato internacional completo
  }),
  lang: 'es',
})

// El código de vinculación llega por el evento 'qr' (el mismo que trae el QR)
bot.on('qr', (code) => console.log('Escribe este código en WhatsApp > Dispositivos vinculados:', code))
```

## ¿El bot funciona en grupos?

Sí. Los handlers `when()` funcionan en grupos por defecto. Para responder
solo en privado:

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

En un grupo, cada participante obtiene una **conversación independiente**
por defecto cuando dispara un flow — dos personas hablándole al bot en el
mismo grupo no comparten estado. Configura `conversationScope: 'chat'` si
en cambio quieres una única conversación compartida por grupo.

## ¿Por qué `bot.when('hola')` no coincide con "hola a todos"?

La estrategia de coincidencia por defecto es **igualdad normalizada**, no
"contains" — el mensaje debe ser igual al trigger exactamente, después de
convertir a minúsculas, quitar acentos y colapsar espacios. Para
coincidencia por subcadena, usa un `TriggerObject`:

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

`match` también acepta `'startsWith'` y `'endsWith'`.

## ¿Puedo enviar botones?

Depende del transporte. Con la Cloud API oficial (`@botmesh/meta`) y con
Telegram, `ctx.buttons(texto, botones)` envía botones **nativos** (ver
[Mensajes y media](https://botmesh.afaya.com.co/es/guide/messages.md)). En Baileys, no: los botones/listas
interactivos nativos están muertos en el protocolo actual de WhatsApp Web.
Usa un menú numerado (`.choose()` en un flow, `c.choose()` en una
conversación) o una encuesta real:

```ts theme={null}
await ctx.poll('¿Confirmas tu pedido?', ['Sí', 'No'])
```

## ¿Los flows/conversaciones sobreviven a un reinicio?

Solo si lo activas explícitamente. `flow(...).persistent()` hace
checkpoint de la conversación después de cada paso, pero el `MemoryStore`
por defecto vive en memoria — un reinicio pierde esos checkpoints a menos
que el store tenga un archivo detrás:

```ts theme={null}
const bot = new Bot({
  provider: new BaileysProvider({ session: 'mi-bot' }),
  lang: 'es',
  store: new MemoryStore({ file: './store.json' }), // o usa @botmesh/sqlite-store
})
```

## ¿Puedo enviar mensajes sin que alguien me escriba primero?

Sí, con `bot.send`:

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

Para enviar un mismo mensaje a muchos chats usa [`bot.broadcast()`](https://botmesh.afaya.com.co/es/guide/messages#difusiones-broadcast)
(por lotes, con reintentos ante rate limits y cancelable); para iniciar un flujo
completo a alguien usa [`bot.trigger()`](https://botmesh.afaya.com.co/es/guide/messages#iniciar-un-flujo-desde-código).
En la Cloud API de WhatsApp, los mensajes libres solo salen dentro de la ventana
de 24 horas: ver [Ventana de 24 h](https://botmesh.afaya.com.co/es/guide/session-window.md).

## ¿Cómo detengo el bot correctamente?

```ts theme={null}
process.on('SIGINT', async () => {
  console.log('🛑 Apagando...')
  await bot.stop({ drain: true }) // espera envíos en curso y respuestas en pausa (hasta `timeout`, 10 s por defecto)
  process.exit(0)
})
```

## ¿Puedo tener varios bots en el mismo proceso?

Sí, con providers/sesiones diferentes:

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

Incluso puedes mezclar transportes — un `Bot` por provider (p. ej. un bot
Baileys y un bot con `CloudAPIProvider` en el mismo proceso).

## ¿Funciona con WhatsApp Business?

Sí. El bot funciona tanto con cuentas personales como con cuentas de
WhatsApp Business.

## ¿Puedo montar un asistente de IA estilo ChatGPT en WhatsApp?

No en la WhatsApp Business Platform. Desde el **15-01-2026** los términos de
Meta **prohíben los asistentes de IA de propósito general** (chatbots
abiertos cuya funcionalidad principal es la propia IA). La IA al servicio de
tu negocio — atención al cliente, ventas, reservas — sí está permitida. Con
`@botmesh/ai`, escribe una persona acotada a tu negocio; mira la
[guía del plugin de IA](https://botmesh.afaya.com.co/es/guide/ai.md#política-de-ia-de-whatsapp-desde-el-15-01-2026).

## ¿Pueden banear mi cuenta?

WhatsApp puede detectar automatización excesiva. Para minimizar el riesgo:

* No envíes spam ni mensajes masivos
* Usa `markOnlineOnConnect: false` (opción de `BaileysProvider`)
* Respeta los límites de rate (el [limiter integrado](https://botmesh.afaya.com.co/es/guide/rate-limiting.md) del provider)
* No respondas instantáneamente a todo (activa el [indicador de escritura](https://botmesh.afaya.com.co/es/guide/messages.md#indicador-de-escritura-y-pausas) con `BotConfig.typing`)
* Considera la [Cloud API](https://github.com/andresayac/botmesh/tree/main/packages/meta-provider) oficial (`@botmesh/meta`) para bots críticos — sin riesgo de baneo

## ¿Necesito TypeScript?

**No.** Todos los ejemplos funcionan en JavaScript plano — solo ten en
cuenta que el paquete es **solo ESM**, así que tu proyecto necesita
`"type": "module"` en el `package.json` (o un archivo `.mjs`)
independientemente de si usas TypeScript. TypeScript te da autocompletado y
type-checking, pero es opcional.

## ¿Por qué me sale `ERR_REQUIRE_ESM` o "require is not defined"?

Estás intentando hacer `require('@botmesh/core')` (o un paquete de
transporte) desde un archivo CommonJS. No hay build de CJS: cambia a
`import` (agrega `"type": "module"` a tu `package.json`, o usa la extensión
`.mjs`). Más errores de instalación (scripts de build de pnpm, módulos
nativos) en [Solución de problemas](https://botmesh.afaya.com.co/es/guide/troubleshooting.md#instalación).

## ¿Dónde está la API reference completa?

En la [API Reference](https://botmesh.afaya.com.co/api/core.md), generada con TypeDoc desde el código fuente y
agrupada por tema (Bot, Messages & context, Flows, Store, Errors…). Cubre las
tres entradas de **`@botmesh/core`** con garantía semver: la principal, `/spi`
(para autores de stores, backends y transportes) y `/testing`.
`@botmesh/core/internal` no se documenta a propósito: no tiene garantía semver.
Los paquetes de canal, store y plugins se documentan en su página de guía y en el
README de cada paquete en npm.

## ¿Sigues teniendo problemas?

* [Solución de problemas](https://botmesh.afaya.com.co/es/guide/troubleshooting.md): los errores frecuentes y cómo resolverlos
* [Abre un issue en GitHub](https://github.com/andresayac/botmesh/issues)
* [Revisa los ejemplos](https://botmesh.afaya.com.co/es/examples.md)


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