SDK quick start

Use the SDK when your application owns the browser and session. Use Node.js 22.21.1 or newer and npm.

Create the botCopy Anchor Link

npm init @open-wa@latest my-bot -- --mode sdk
cd my-bot
npm start

Choose JavaScript or TypeScript, your browser, and any plugins in the wizard. You can also use the project builder to preview the generated files and copy a command with every choice filled in.

The project includes index.js or index.ts, the matching wa.config file, a start script, and ignore rules. TypeScript projects include editor types and tsconfig.json; Node.js runs these starter files directly.

If you selected a plugin that needs credentials, copy .env.example to .env and fill it in before running npm start.

Connect and handle messagesCopy Anchor Link

Scan the terminal QR code using WhatsApp → Linked devices → Link a device on your phone. Once ready, send !ping from another WhatsApp account. The starter responds pong and keeps running.

The JavaScript entry point looks like this; the TypeScript choice uses the same flow and imports wa.config.ts:

import { create } from '@open-wa/wa-automate';
import config from './wa.config.js';

const client = await create(config);
console.log('WhatsApp is ready. Send !ping from another account.');

client.onMessage(async message => {
  if (!message.fromMe && message.body === '!ping') {
    await client.sendText(message.from, 'pong');
  }
});

for (const signal of ['SIGINT', 'SIGTERM']) {
  process.once(signal, () => {
    void client.stop(signal).catch(console.error);
  });
}

The handler reuses message.from, including @lid identities. It sends only when someone types !ping; startup itself doesn't send a greeting. Add your own handlers here. See create(), client methods, and the chat ID guide.

Configure browsers and pluginsCopy Anchor Link

Edit wa.config.js or wa.config.ts. The entry point passes it to create(); it isn't implicitly loaded by the SDK. The generated config also loads .env when present. Browser selections and plugins use the same setup options as Easy API. They download only when needed and are cached.

SDK mode doesn't start an HTTP server or Neo dashboard. Use Easy API if you want those surfaces. Chatwoot requires Easy API webhook routes, so the initializer excludes it from SDK mode. Voxtral can run in the SDK using its file settings; see the Voxtral guide.

Stop and restartCopy Anchor Link

Press Ctrl+C to stop the client and browser. Run npm start again from the same directory to reuse a valid saved session. Keep .env and session data private. If a send fails with an uncertain result, inspect the receiving chat before retrying it.