Instalación

Requisitos

• Node.js 22 o superior (descargar)
• pnpm (recomendado) o npm/yarn
• Un teléfono con WhatsApp (para el transporte Baileys)

¿No tienes pnpm?

Instálalo con:

npm install -g pnpm

Paquetes solo ESM

@botmesh/core y los paquetes de transporte se distribuyen como ESM puro — no hay build de CommonJS. Tu proyecto necesita "type": "module" en su package.json (o una extensión de archivo .mjs). En Node >= 22.12 también puedes hacer require() gracias al soporte experimental require(esm) de Node, pero los ejemplos de abajo usan import normal.

Alpha — publicada bajo el tag alpha

botmesh está en alpha: todos los paquetes están en npm, pero solo bajo el dist-tag alpha (changeset publish no crea latest). Una instalación sin tag no resuelve, así que escribe siempre pnpm add @botmesh/core@alpha. Cuando salga una versión estable el tag se puede omitir.

Crear un proyecto con create-botmesh

La forma más rápida de empezar es la CLI create-botmesh, que genera un proyecto listo para ejecutar. Para ejecutarla desde una copia de este monorepo, apunta fuera del repo (pnpm --filter create-botmesh build && node packages/create-botmesh/lib/cli.js ../my-bot; un destino dentro del monorepo de botmesh se rechaza salvo que pases --force):

npm create botmesh@alpha my-bot
npm create botmesh@alpha my-bot -- --template telegram --yes

Plantilla	Qué obtienes
baileys (por defecto)	WhatsApp vía Baileys: escaneas un QR para vincular
meta	WhatsApp Cloud API (webhook; necesita credenciales de Meta y una URL pública)
telegram	Telegram Bot API (long-polling; necesita un token de @BotFather)
ai	Baileys + autorespondedor de soporte con @botmesh/ai limitado al negocio (ANTHROPIC_API_KEY)
games	Adivina el número, ahorcado, trivia, tres en raya, piedra-papel-tijera; puntuaciones en ctx.user
support	Tickets por usuario, menú de FAQ y handoff a humano
store	Catálogo, carrito por usuario con TTL de 7 días y flujo de checkout
restaurant	Menú, pedidos a domicilio o para recoger, "repetir mi último pedido", reservas de mesa
clinic	Agenda de citas (especialidad, día, hora), listar y cancelar citas
ai-full	IA limitada al negocio + intents por palabra clave/regex + store SQLite + scheduler + comandos slash + handoff (ANTHROPIC_API_KEY)

Las plantillas de casos de uso (de games a ai-full) usan Baileys. Las de transporte (baileys, meta, telegram, ai) instalan los comandos slash integrados (/help, /reset, /cancel, /id, /ping), así que /reset o /cancel sale de su flujo de ejemplo menu.

Flag	Significado
-t, --template <name>	Una de las plantillas de arriba (baileys en modo no interactivo)
--name <name>	Nombre del paquete (por defecto, el del directorio)
-y, --yes	Omite las preguntas y usa los valores por defecto
--overwrite	Permite generar en un directorio que no está vacío
--force	Permite un directorio dentro del propio monorepo de botmesh (rechazado por defecto)
-h, --help	Muestra la ayuda

Cada proyecto incluye package.json (con npm start y npm run dev, el simulador en la terminal), src/bot.js, .env.example, .gitignore, README.md y un AGENTS.md con instrucciones para agentes de código con IA: la API v2 actual, lo que no existe (addAnswer, capture...) y los comandos que hay que ejecutar.

npm run dev no necesita credenciales. npm start en los proyectos meta, telegram, ai y ai-full comprueba las variables sin las que no puede arrancar y, si falta el .env o está incompleto, se detiene con una línea que las nombra (Missing TELEGRAM_TOKEN: copy .env.example to .env ...) antes de conectar nada.

El package.json generado depende de los paquetes @botmesh/* publicados bajo el dist-tag alpha (^2.0.0-alpha.2 para el core, ^0.2.0-alpha.0 para el resto; los rangos exactos salen de create-botmesh/src/versions.ts, generado en el build). Todavía no hay latest, así que instalarlos a mano requiere @alpha. Para apuntar esas dependencias a tu copia local del monorepo, usa rangos workspace:.

Si prefieres montarlo todo a mano, sigue los pasos de abajo.

Paso 1 — Instalar el framework

El motor (@botmesh/core) es agnóstico de transporte: lo emparejas con un paquete provider. Para WhatsApp vía Baileys 7 (no oficial, login por QR):

mkdir my-bot
cd my-bot
pnpm init
pnpm add @botmesh/core@alpha @botmesh/baileys@alpha

Otros transportes detrás del mismo contrato IProvider:

Transporte	Paquete	Estado	Notas
WhatsApp (Baileys 7)	@botmesh/baileys	Alpha	No oficial, login por QR — el que usa esta guía
WhatsApp Cloud API	@botmesh/meta	Alpha	API oficial de Meta, por webhook, sin riesgo de baneo
Telegram	@botmesh/telegram	Alpha	Bot API, long-poll o webhook
Facebook Messenger	@botmesh/messenger	Experimental	Send API de Meta Graph, por webhook
Instagram DM	@botmesh/instagram	Experimental	Meta Graph, por webhook
Discord	@botmesh/discord	Experimental	Gateway websocket + REST

Los paquetes Alpha están publicados en npm bajo el dist-tag alpha (instálalos con @alpha). Los Experimental son implementaciones reales y con tests que de momento siguen siendo privadas (sin publicar) y pueden cambiar. Hay más providers experimentales (Evolution API, WPPConnect, Twilio, HighLevel, Gupshup, Email y TikTok) y una matriz de capacidades en Canales.

Luego agrega "type": "module" al package.json generado para que Node trate tus archivos como ESM:

{
  "type": "module"
}

Paso 2 — Crear tu bot

Crea un archivo bot.js. En v2, crear un bot requiere un provider — las opciones de sesión/auth de WhatsApp viven en el provider, no en el bot:

import { Bot } from '@botmesh/core'
import { BaileysProvider } from '@botmesh/baileys'

const bot = new Bot({
  provider: new BaileysProvider({
    session: 'my-bot',
    qr: { terminal: true, small: true },
  }),
})

bot.on('ready', () => console.log('✅ Bot connected!'))

bot.when('hola', async (ctx) => {
  await ctx.reply('👋 Hello! I am your bot.')
})

await bot.start()

Paso 3 — Ejecutar y escanear el QR

node bot.js

Verás un código QR en tu terminal. Ábrelo en tu teléfono:

1. Abre WhatsApp
2. Ve a Configuración → Dispositivos vinculados
3. Toca Vincular un dispositivo
4. Escanea el código QR

¡Listo! Tu bot está conectado. Envía "hola" (exactamente, ese es el modo de coincidencia por defecto) desde otro teléfono y recibirás una respuesta.

No escanees con el mismo teléfono

El QR se escanea con el teléfono que será el bot, no con el que envía los mensajes.

Otros transportes, mismo código de bot

Solo cambia el provider — when/flow/hooks/plugins son idénticos en todos los transportes. Para la Cloud API oficial de WhatsApp:

import { Bot } from '@botmesh/core'
import { CloudAPIProvider } from '@botmesh/meta'

const bot = new Bot({
  provider: new CloudAPIProvider({
    accessToken: process.env.META_TOKEN ?? '',
    phoneNumberId: process.env.META_PHONE_ID ?? '',
    verifyToken: process.env.META_VERIFY_TOKEN ?? '',
    appSecret: process.env.META_APP_SECRET, // obligatorio: verifica X-Hub-Signature-256
  }),
})

(La Cloud API es por webhook: pasa el body crudo de cada POST entrante a provider.ingest(rawBody, headers) desde tu servidor HTTP — la firma se calcula sobre los bytes exactos que envió Meta. Sin appSecret el constructor lanza un error; allowUnsignedWebhooks: true existe solo para desarrollo local aislado.) Consulta Canales para el resto de transportes y Servidor de webhooks para montar los providers por webhook.

Siguientes pasos

• Tu primer bot — un bot completo con comandos, media y flujos
• Conceptos básicos — entiende cómo funciona todo
• Simulador en la terminal — chatea con tu bot sin teléfono (npx botmesh dev src/bot.js)
• Ejemplos — recetas listas para copiar