Salta el boilerplate: clona un bot que ya funciona
Esta guía usa el bot open-source del repositorio GitHub de Whapi.Cloud. Ya cubre envío y recepción, media, contactos, productos y grupos. El resto del artículo explica cómo ponerlo en marcha.
El script de este chatbot incluye las funciones básicas que suelen utilizar las pequeñas y medianas empresas, cubriendo la mayoría de las tareas:
- Enviar un mensaje normal;
- Enviar multimedia: imagen/archivo/video;
- Enviar un contacto (tarjeta de visita vCard);
- Enviar un producto;
- Crear un grupo de WhatsApp;
- Enviar una invitación al grupo;
- Enviar un mensaje a un grupo de WhatsApp;
- Recibir y procesar mensajes entrantes;
- Responder a un comando desconocido (para implementar menús, instrucciones o un mensaje de bienvenida).
git clone https://github.com/Whapi-Cloud/nodejs-whatsapp-chatbot
Después de clonar, entra en la carpeta del proyecto:
cd nodejs-whatsapp-chatbot
Instala los paquetes de
package.json:
npm install
Así se descargan las dependencias que el chatbot necesita para arrancar.
Estructura del proyecto
- /files — media de ejemplo que el bot puede enviar (imagen, PDF, vídeo, vCard). Cámbialos cuando quieras.
- config.js —
token,botUrl,porte IDs opcionales degroup/product. - index.js — registra el webhook, escucha en
/hook/messagesy mapea los números 1–9 a acciones.
Conecta tu número de WhatsApp
Whapi.Cloud es un gateway HTTP para WhatsApp, independiente de Meta. Puedes usar cualquier número que ya tengas, escanear un QR en el panel y obtener un token Bearer. No hay verificación Meta Business ni límites de plantillas o ventana de mensajería de Cloud API.
Para que el bot funcione no hace falta que el teléfono esté en línea. Vincula el número una vez en el panel y ejecuta el bot en cualquier servidor. Si necesitas ayuda, usa el chat de soporte del sitio.
Escanea el código QR en tu cuenta
Registro. El primer paso es registrarte en la web de Whapi.Cloud y crear una cuenta. Es gratis y no pide tarjeta.
Tras registrarte tendrás enseguida un canal de prueba con un cupo reducido. Espera a que arranque (suele tardar un minuto). Tendrás que vincular el teléfono: desde ese número se enviarán los mensajes. La ventaja es que en un par de minutos ya estás trabajando.
Para vincular el teléfono, usa el QR al hacer clic en el canal de prueba de tu cuenta. Abre WhatsApp en el móvil: Ajustes -> Dispositivos vinculados -> Vincular dispositivo -> Escanear código QR.
Puedes saltarte las pantallas de nombre de canal y webhook del asistente: el bot configurará el webhook al arrancar.
Ya tienes el token de API: lo necesitarás para probar y llamar a los endpoints. Guárdalo, lo usarás más de una vez. En la ficha del canal, cópialo y pégalo en
config.js como token. Las peticiones a https://gate.whapi.cloud lo llevan como Bearer.
Antes de arrancar el bot
- Token del canal pegado en
config.js. - Un segundo teléfono para probar: el bot ignora los mensajes del número conectado.
- URL HTTPS pública. En local usa ngrok; en producción, cualquier host con HTTPS.
Dale al bot una URL HTTPS pública
Un webhook es el aviso que Whapi.Cloud envía a tu bot cada vez que pasa algo en la cuenta de WhatsApp conectada: un texto nuevo, un cambio de estado, una invitación a grupo.
En lugar de preguntar «¿hay mensajes nuevos?» una y otra vez, tu script recibe un POST con el evento en cuanto ocurre.
Ejemplo: el contacto A te escribe «hola» -> Whapi.Cloud hace POST de un JSON a
/hook/messages en tu servidor -> el bot mira el comando y responde. No pegas la URL en el panel; el bot la registra desde config.js al arrancar.Whapi.Cloud entrega los mensajes entrantes con un POST a tu URL HTTPS pública. No la pegas en el panel. Ponla en
config.js como botUrl; al arrancar el repo la registra con la API de ajustes del canal.Túnel local con ngrok
El
port por defecto en config.js es 80 (no uses 443). Descarga ngrok y ejecuta ngrok http 80 — o el puerto que hayas puesto en config.js.Copia la URL de reenvío
https://. Pon botUrl a ese host más /hook, por ejemplo botUrl: "https://84c7-151-33-282-113.ngrok-free.app/hook".
Mantén el sufijo
/hook. El servidor escucha POST en /hook/messages; botUrl es el prefijo que queda en los ajustes del canal.Al ejecutar
node index.js, el bot envía PATCH /settings con esa URL y el evento messages. Los mensajes de WhatsApp llegan entonces a tu proceso. Puedes ignorar los campos de webhook del panel salvo que quieras ver qué se registró.Qué necesita producción
El host tiene que ser alcanzable por internet en HTTPS, y el proceso Node debe seguir en marcha para aceptar POST. Si cambias
botUrl, reinicia el bot para que vuelva a registrar el webhook.Arrancar el bot
Confirma
token y botUrl en config.js y, desde la raíz del proyecto, ejecuta node index.js. Deberías ver un log de listening. Desde otro teléfono, envía cualquier texto al número conectado. El bot responde con un menú numerado.Menú de comandos
- Mensaje de texto simple
- Enviar imagen
- Enviar documento
- Enviar vídeo
- Enviar contacto
- Enviar producto
- Crear grupo
- Texto simple al grupo
- Obtener los ids de tus tres grupos
Envía solo el número, por ejemplo 1. Cualquier otra cosa vuelve a devolver esta lista.
Los comandos 6 y 8 usan
product y group en config.js. Sáltalos en la primera prueba. Cuando los necesites, lista IDs con GET /groups y GET /business/products.Solución de problemas
El bot no responde
Escribe desde otro teléfono: el script ignora
from_me. Comprueba el token, que botUrl termine en /hook, que ngrok (o tu host) siga activo y que el proceso haya imprimido el mensaje de listening.El bot envía mensajes en bucle
Mantén
if (message.from_me) continue. Sin eso el bot responde a sus propios mensajes y no para.Funciona en unos chats y en otros no
Sandbox limita las conversaciones activas (ahora 5 al mes). Un sexto chat no recibirá respuestas hasta que subas de plan o se reinicie el cupo.
Enviar mensajes de WhatsApp desde Node.js
El bot clonado ya envía, recibe, media, contactos, productos, grupos y más. Los snippets de abajo son el mismo patrón HTTP que usa por dentro: un
fetch a https://gate.whapi.cloud con tu token Bearer.Enviar un mensaje de texto
Envía un texto plano a un chat o a un grupo:
const response = await fetch('https://gate.whapi.cloud/messages/text', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '[email protected]',
body: 'Hello from the cloned bot'
})
});
const data = await response.json();
console.log(data);
Enviar un documento
Envía un documento con una URL pública o un payload en base64:
const response = await fetch('https://gate.whapi.cloud/messages/document', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '[email protected]',
media: 'https://example.com/file.pdf',
caption: 'Document from the bot'
})
});
const data = await response.json();
console.log(data);
La lista completa de tipos y payloads está en la referencia de la API.
Trabajar con grupos de WhatsApp
El bot puede listar los grupos en los que participas y reaccionar a mensajes de grupo. Estos ejemplos reutilizan el mismo Bearer y el endpoint
/groups.Listar tus grupos
Trae los grupos visibles para el número conectado:
const response = await fetch('https://gate.whapi.cloud/groups', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
});
const { groups } = await response.json();
console.log(groups);
Cada objeto de grupo incluye nombre, foto, descripción y un array de participantes.
Contar participantes del grupo
Recorre el array para imprimir el nombre de cada grupo y el número de miembros:
groups.forEach(group => {
console.log(`Group Name: ${group.name}`);
console.log(`Participants: ${group.participants.length}`);
});
Gestionar mensajes de grupo
Los IDs de chat de grupo terminan en
@g.us. Los webhooks entrantes usan el mismo sufijo; el bot clonado ya ramifica por ahí cuando un comando apunta a un grupo.
// Del bot clonado: los mensajes de grupo usan chat_id que termina en @g.us
const messages = req.body.messages;
messages.forEach(message => {
if (message.chat_id.endsWith('@g.us')) {
console.log(`Group message: ${message.text?.body}`);
}
});
Para crear grupos, invitar o gestionar admins, mira la guía de grupos en la documentación.
El comando 7 crea un grupo con el remitente como participante. El 8 escribe a
config.group. Pon ese ID antes de usar esos números.Déjalo en línea
Deja
node index.js corriendo en una máquina con URL HTTPS pública y pon botUrl a https://tu-host/hook. Este bot es un proceso Express de larga duración, no una función serverless de un disparo: vale un VPS o cualquier host Node con HTTPS. Reinicia si cambias botUrl para registrar de nuevo el webhook.Para que tu chatbot de WhatsApp esté disponible 24/7, necesita estar alojado en una plataforma de hosting confiable. Puedes usar tu propio servidor, pero en este capítulo examinaremos las tres plataformas más populares —Firebase, AWS y Heroku— y repasaremos los pasos básicos para desplegar tu bot en cada una de ellas.
La elección de la plataforma depende de tus preferencias, presupuesto y requisitos del proyecto. Cada una de las plataformas examinadas ofrece sus propias capacidades únicas y ventajas. Firebase y AWS Lambda proporcionan un potente backend sin la necesidad de gestionar un servidor, mientras que Heroku ofrece simplicidad en el despliegue de aplicaciones basadas en Git.
Firebase
Firebase ofrece la funcionalidad de Cloud Functions, que te permite ejecutar tu bot sin tener que preocuparte por la infraestructura del servidor. En nuestra opinión, esta es la opción más óptima.
- Crea un proyecto en Firebase Console;
- Instala Firebase CLI, siguiendo las instrucciones;
- Inicializa Firebase en el directorio de tu proyecto con el comando firebase init;
- Despliega tu bot usando el comando firebase deploy --only functions.
AWS (Amazon Web Services)
AWS Lambda permite ejecutar código en respuesta a desencadenantes de otros servicios de AWS, lo que lo convierte en una buena elección para un bot.
- Regístrate o inicia sesión en AWS Management Console;
- Crea una nueva función Lambda a través de la consola de AWS, eligiendo API Gateway como desencadenante;
- Sube el código de tu bot a la función Lambda;
- Configura API Gateway para que tu bot interactúe con el mundo exterior.
Heroku
Heroku ofrece una plataforma de alojamiento de aplicaciones fácil de usar que puede desplegar automáticamente el código desde tu repositorio Git.
- Crea una cuenta en Heroku;
- Instala Heroku CLI e inicia sesión;
- Crea una nueva aplicación en Heroku a través de la consola o usando el comando heroku create;
- Conecta tu repositorio Git con Heroku y realiza el despliegue con los comandos git push heroku master;
- Configura la URL del webhook proporcionada por Heroku.
Siguientes pasos
Con el bot en marcha puedes construir encima. Envía archivos con una URL pública; reparte leads entrantes en grupos de WhatsApp; conecta un CRM para que reservas y pedidos se actualicen al momento; usa encuestas como alternativa ligera a los botones; publica estados y reacciona a los mensajes para mantener el hilo; o valida números antes de un envío masivo. Mira la documentación o explora grupos, canales, comunidades, MCP, n8n, Make, agent skills y el hub de chatbots.
