Cómo Vincular WhatsApp con Node.js

whatsmeow-node se conecta a WhatsApp como un dispositivo vinculado — igual que WhatsApp Web o Desktop. Puedes vincular usando un QR code o un código de número telefónico. Una vez vinculado, la sesión se persiste y tu aplicación se reconecta automáticamente.

Requisitos Previos

• whatsmeow-node instalado (Guía de instalación)
• Una cuenta de WhatsApp en tu teléfono

Método 1: Vinculación por QR Code

El flujo estándar — tu terminal muestra un QR code que escaneas con WhatsApp.

import { createClient } from "@whatsmeow-node/whatsmeow-node";
import qrcode from "qrcode-terminal";

const client = createClient({ store: "session.db" });

// Display QR codes in the terminal
client.on("qr", ({ code }) => {
  qrcode.generate(code, { small: true });
});

client.on("connected", ({ jid }) => {
  console.log(`Paired and connected as ${jid}!`);
});

async function main() {
  const { jid } = await client.init();

  if (jid) {
    // Already paired — just connect
    console.log(`Session found for ${jid}`);
    await client.connect();
    return;
  }

  // Not paired — set up QR channel first
  await client.getQRChannel();
  await client.connect();
}

main().catch(console.error);

Instala qrcode-terminal con npm install qrcode-terminal (y npm install -D @types/qrcode-terminal si usas TypeScript).

info

Los QR codes expiran y se actualizan automáticamente. Si el usuario no escanea a tiempo, se emite un nuevo QR code a través del evento "qr".

Método 2: Vinculación por Número Telefónico

En lugar de escanear un QR, el usuario ingresa un código de 8 caracteres en WhatsApp. Útil para servidores sin pantalla o cuando la visualización de QR en terminal no es práctica.

const client = createClient({ store: "session.db" });

async function main() {
  const { jid } = await client.init();

  if (jid) {
    await client.connect();
    return;
  }

  // Step 1: Connect first — pairCode() requires an active connection
  await client.connect();

  // Step 2: Request a pairing code
  const phoneNumber = "5512345678"; // without the + prefix
  const code = await client.pairCode(phoneNumber);
  console.log(`Pairing code: ${code}`);
  console.log("Enter this in: WhatsApp → Linked Devices → Link with phone number");

  // Step 3: Wait for the user to enter the code
  client.once("connected", ({ jid }) => {
    console.log(`Paired as ${jid}!`);
  });
}

main().catch(console.error);

aviso

pairCode() debe llamarse después de connect() — requiere una conexión activa a los servidores de WhatsApp. El código expira después de 60 segundos.

Persistencia de Sesión

Una vez vinculado, la sesión se almacena en la base de datos que especificaste. En la siguiente ejecución, init() devuelve el JID almacenado y puedes omitir el flujo de vinculación:

const { jid } = await client.init();
if (jid) {
  // Already paired — connect directly
  await client.connect();
} else {
  // First run — pair first
  await client.getQRChannel();
  await client.connect();
}

Elegir un Almacén

Almacén	URI	Ideal para
SQLite	"session.db" o "file:./data/session.db"	Desarrollo, instancia única
PostgreSQL	"postgresql://user:pass@host/db"	Producción, múltiples instancias

Las rutas de archivo simples se normalizan automáticamente con el prefijo file:.

Ejemplo Completo

Maneja tanto la vinculación inicial como la reconexión:

import { createClient } from "@whatsmeow-node/whatsmeow-node";
import qrcode from "qrcode-terminal";

const client = createClient({ store: "session.db" });

client.on("qr", ({ code }) => {
  qrcode.generate(code, { small: true });
});

client.on("connected", ({ jid }) => {
  console.log(`Connected as ${jid}`);
});

client.on("logged_out", ({ reason }) => {
  console.error(`Session revoked: ${reason} — delete session.db and re-pair`);
  client.close();
  process.exit(1);
});

async function main() {
  const { jid } = await client.init();

  if (jid) {
    console.log(`Resuming session for ${jid}`);
    await client.connect();
  } else {
    console.log("No session found — pairing...");
    await client.getQRChannel();
    await client.connect();
  }

  process.on("SIGINT", async () => {
    await client.disconnect();
    client.close();
    process.exit(0);
  });
}

main().catch(console.error);

Errores Comunes

pairCode() antes de connect()

Llamar a pairCode() antes de connect() fallará. El flujo de vinculación por número telefónico requiere una conexión WebSocket activa a los servidores de WhatsApp.

Usa el formato internacional

Pasa el número completo con su código de país, p. ej. "5512345678". Los caracteres que no son dígitos, como +, espacios y guiones, se eliminan automáticamente, pero un número que empieza con 0 (formato local) se rechaza.

Revocación de sesión

Si el usuario desvincula el dispositivo desde WhatsApp (Configuración → Dispositivos vinculados → eliminar), se dispara el evento "logged_out". La única recuperación es eliminar la base de datos de sesión y vincular nuevamente.

Siguientes Pasos

• Cómo Crear un Bot — vincula y luego construye un bot
• Primeros Pasos — resumen rápido de la API completa
• Ciclo de Vida de Conexión — profundización en los estados de conexión
• Ejemplos de Vinculación — más ejemplos de código de vinculación