[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-10314":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":23,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":16,"starSnapshotCount":16,"syncStatus":17,"lastSyncTime":33,"discoverSource":34},10314,"wa-automate-nodejs","open-wa\u002Fwa-automate-nodejs","open-wa"," 💬 🤖  The most reliable tool for chatbots with advanced features. Be sure to 🌟 this repository for updates! ","https:\u002F\u002Fdocs.openwa.dev\u002F",null,"TypeScript",3612,711,103,154,0,2,161,30.56,"Other",false,"master",true,[25,26,27,28,29],"api","chatbots","framework","nodejs","typescript","2026-06-12 02:02:20","> [!WARNING]\n> By using this project you explicitly agree to the [Terms of Service](.\u002Ftos.md).\n>\n> This project is unofficial and is not affiliated with WhatsApp or Meta. Use it at your own risk.\n\n> [!CAUTION]\n> This repository is currently on version 5, which is still in alpha and may have issues.\n>\n> For now, use version 4 instead unless you are explicitly testing or contributing to v5.\n> The last stable version is 4.76.0\n> `npx @open-wa\u002Fwa-automate4.76.0`\n\n\u003Cdiv align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Fraw.githubusercontent.com\u002Fopen-wa\u002Fwa-automate-nodejs\u002Fmaster\u002Fresources\u002Fhotfix-logo.png\" width=\"128\" height=\"128\"\u002F>\n\n# open-wa \u002F wa-automate\n\n**Connect a WhatsApp account, turn it into an API, automate it, and extend it.**\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@open-wa\u002Fwa-automate.svg?color=green)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@open-wa\u002Fwa-automate)\n![node](https:\u002F\u002Fimg.shields.io\u002Fnode\u002Fv\u002F@open-wa\u002Fwa-automate)\n[![Downloads](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fdm\u002F@open-wa\u002Fwa-automate.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@open-wa\u002Fwa-automate)\n\u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002Fdnpp72a\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F661438166758195211?color=blueviolet&label=discord&style=flat\" \u002F>\u003C\u002Fa>\n\n\u003C\u002Fdiv>\n\n## What this is\n\n`@open-wa\u002Fwa-automate` gives you a few practical ways to automate WhatsApp:\n\n- run a ready-made API with the CLI\n- connect another app to that runtime\n- embed the runtime directly in your own Node.js code\n- add integrations and plugins\n\nThis repository is currently a **v5 monorepo** and the package version in this repo is **`5.0.0-alpha.1`**. If you are migrating a mature v4 production system, test v5 in a separate environment first.\n\nIf you only want the fastest, least-confusing first run, start with **Easy API** below.\n\n## Start with the path that matches you\n\n| If you want to... | Start here |\n| --- | --- |\n| get WhatsApp connected fast and use it from another service | [Quick start: Easy API](#quick-start-easy-api) |\n| build a simple Node automation quickly | [Simple automation: SocketClient](#simple-automation-socketclient) |\n| own the runtime inside your own app | [Deep integration: embedded runtime](#deep-integration-embedded-runtime) |\n| upgrade existing v4 code carefully | [Migrating from v4 to v5](#migrating-from-v4-to-v5) |\n| publish or share a reusable extension | [Plugins and integrations](#plugins-and-integrations) |\n\n## Quick start: Easy API\n\nIf you just want to connect a WhatsApp account and get a working API, this is the fastest path:\n\n```bash\nnpx @open-wa\u002Fwa-automate --port 8080\n```\n\nThat starts an Easy API instance and gives you the first-run authentication flow plus interactive docs for the running session.\n\n**v5 is alpha right now**, so prefer explicit commands like the one above instead of relying on undocumented defaults.\n\nFor first login, either:\n\n- scan the QR code the runtime prints, or\n- use link-code login if that fits your setup better\n\nThen open:\n\n```text\nhttp:\u002F\u002Flocalhost:8080\u002Fapi-docs\u002F\n```\n\nThat is the clearest first proof that your session is up and the API is live.\n\nOther useful generated artifacts:\n\n```text\nhttp:\u002F\u002Flocalhost:8080\u002Fmeta\u002Fswagger.json\nhttp:\u002F\u002Flocalhost:8080\u002Fmeta\u002Fpostman.json\n```\n\nUseful first commands:\n\n```bash\n# choose a port\nnpx @open-wa\u002Fwa-automate --port 8080\n\n# provide your own API key\nnpx @open-wa\u002Fwa-automate --port 8080 --api-key \"your-secure-key\"\n\n# run a named session\nnpx @open-wa\u002Fwa-automate --session-id sales --port 8081\n\n# send events to your service\nnpx @open-wa\u002Fwa-automate --webhook \"https:\u002F\u002Fyour-app.example\u002Fwebhooks\u002Fopen-wa\"\n```\n\nGood defaults for a first session:\n\n- set a `sessionId` early if you might run more than one account\n- protect the API with an `--api-key` before exposing it outside your machine\n- keep business logic in your own app and let open-wa own the WhatsApp runtime\n\nIf your goal is simply “connect WhatsApp to another service”, add `--webhook` first and write no custom runtime code until you know you need it.\n\nIf you prefer Docker:\n\n```bash\ndocker run -p 8080:8080 --init openwa\u002Fwa-automate\n```\n\nDocker notes:\n\n- this is best for local testing or a disposable first run unless you also plan session persistence properly\n- `--init` is recommended so zombie processes are cleaned up properly\n- you can pin the library version with `W_A_V`, for example `-e W_A_V=4.42.1`\n\n## Simple automation: SocketClient\n\nIf you want to build a bot or workflow quickly without embedding the full browser runtime in your app, run Easy API in one place and connect to it from your code.\n\nStart the runtime:\n\n```bash\nnpx @open-wa\u002Fwa-automate --port 8080 --api-key \"your-secure-key\"\n```\n\nInstall the remote consumer in your app:\n\n```bash\nnpm install @open-wa\u002Fsocket-client\n```\n\nKeep the Easy API process running. Your app is a remote consumer, not the runtime host.\n\nThen connect from your app:\n\n```ts\nimport { SocketClient } from '@open-wa\u002Fsocket-client';\n\nasync function start() {\n  const client = await SocketClient.connect('http:\u002F\u002Flocalhost:8080', 'your-secure-key');\n\n  client.onMessage(async (message) => {\n    if (message.body === 'Hi') {\n      await client.sendText(message.from, '👋 Hello!');\n    }\n  });\n}\n\nstart().catch(console.error);\n```\n\nWhy this path is good for most builders:\n\n- open-wa owns the browser automation runtime\n- your app stays small and focused on automation logic\n- the current v5 runtime uses **HTTP RPC for commands** and **Server-Sent Events for runtime events** behind the compatibility client\n\nThis is usually the best choice if you are technical but just want to build a simple automation fast.\n\n## Deep integration: embedded runtime\n\nIf you want the most control and are comfortable owning browser\u002Fruntime setup directly, use the embedded runtime path.\n\nThe v5 public contract exposes `createClient` from `@open-wa\u002Fcore` through `@open-wa\u002Fwa-automate`.\n\nThis path is lower-level than Easy API + SocketClient. Use it when you want runtime ownership, not when you just want the quickest working bot.\n\n```bash\nnpm install @open-wa\u002Fwa-automate @open-wa\u002Fdriver-puppeteer\n```\n\n```ts\nimport { createClient } from '@open-wa\u002Fwa-automate';\nimport { PuppeteerDriver } from '@open-wa\u002Fdriver-puppeteer';\n\nasync function start() {\n  const client = await createClient({\n    sessionId: 'sales',\n    driver: new PuppeteerDriver(),\n    headless: true,\n  });\n\n  client.onMessage(async (message) => {\n    if (message.body === 'Hi') {\n      await client.sendText(message.from, '👋 Hello!');\n    }\n  });\n}\n\nstart().catch(console.error);\n```\n\nImportant v5 reality:\n\n- the repo’s current **public contract** centers on `createClient`\n- some docs are still being reorganized from the older v4-era shape\n- pluggable browser drivers are now part of the architecture\n\nAvailable runtime driver packages in this repo:\n\n- `@open-wa\u002Fdriver-puppeteer`\n- `@open-wa\u002Fdriver-playwright`\n- `@open-wa\u002Fdriver-lightpanda`\n\nUse the embedded path when you need deeper control over browser selection, runtime lifecycle, or infrastructure behavior.\n\n## Configuration and CLI\n\nCommon config fields documented in the repo’s current config schema and docs include:\n\n- `sessionId`\n- `headless`\n- `useChrome` \u002F `executablePath`\n- `qrTimeout` \u002F `authTimeout`\n- `licenseKey`\n- `linkCode`\n- `plugins`\n- `pluginConfig`\n\nCommon high-value CLI flags include:\n\n```bash\n--port 8080\n--api-key \"your-secure-key\"\n--webhook \"https:\u002F\u002Fyour-app.example\u002Fwebhooks\u002Fopen-wa\"\n--session-id sales\n--pm2\n--license-key \"YOUR-LICENSE-KEY\"\n```\n\nSome older docs and examples still mention additional legacy or transitional flags. For v5 alpha onboarding, prefer the smaller set above unless you have verified the exact flag against the version you are running.\n\nFor contributors to this monorepo, the repo currently declares:\n\n- **Node.js** `>=22.21.1`\n- **pnpm** `>=10.25.0`\n\n```bash\npnpm install\npnpm build\n```\n\n## Plugins and integrations\n\nThis repo is no longer just a single package. It includes a plugin\u002Fintegration surface for extending the runtime.\n\nRelevant packages in this repo:\n\n- `@open-wa\u002Fplugin-sdk`\n- `@open-wa\u002Fintegration-webhook`\n- `@open-wa\u002Fintegration-chatwoot`\n- `@open-wa\u002Fintegration-s3`\n- `@open-wa\u002Fintegration-cloudflare`\n- `@open-wa\u002Fnode-red`\n\n### Loading plugins\n\nThe current config schema supports plugin references as npm package names or file paths:\n\n```ts\nplugins: [\n  '@open-wa\u002Fintegration-chatwoot',\n  '@open-wa\u002Fintegration-webhook',\n  '.\u002Fmy-local-plugin'\n],\npluginConfig: {\n  webhook: {\n    \u002F\u002F plugin-specific config\n  }\n}\n```\n\n### If you want to share a bot or plugin\n\nThe safest documented path today is:\n\n1. build it as an npm package or local package\n2. expose it through the plugin SDK\n3. tell users which `plugins` and `pluginConfig` entries they need\n\nGood examples to copy from in this repo:\n\n- [`.\u002Fintegrations\u002Fwebhook`](.\u002Fintegrations\u002Fwebhook)\n- [`.\u002Fintegrations\u002Fchatwoot`](.\u002Fintegrations\u002Fchatwoot)\n- [`.\u002Fintegrations\u002Fcloudflare`](.\u002Fintegrations\u002Fcloudflare)\n\nWhat is **not** clearly documented yet as a stable public workflow:\n\n- a public plugin marketplace\n- a formal plugin discovery registry for community downloads\n\nSo today, “share a plugin” realistically means “publish a package people can install and load”.\n\n### Built-in integration examples\n\n- **Webhook**: push events into your own service\n- **Chatwoot**: connect open-wa to Chatwoot for bidirectional message handling\n- **Cloudflare Session Proxy**: remote session access without opening public ports\n- **Node-RED**: low-code visual automation on top of Easy API\n\n## Cloudflare Session Proxy\n\nIf you want remote access without exposing local ports, this repo ships `@open-wa\u002Fcf-proxy`.\n\nHigh-level flow:\n\n1. deploy the Worker to your Cloudflare account\n2. attach your session to that proxy as the upstream\n3. connect consumers through the proxy URL\n\nExample consumer connection:\n\n```ts\nimport { SocketClient } from '@open-wa\u002Fsocket-client';\n\nconst client = await SocketClient.connect(\n  'cf-proxy:\u002F\u002Fopen-wa-proxy.account.workers.dev?sessionId=my-session&token=CONSUMER_TOKEN'\n);\n```\n\nThis is the cleanest path if you want remote access but do not want to invent your own transport bridge.\n\n## AI-agent integration (MCP)\n\nIf your goal is to let an AI agent interact with WhatsApp, the cleanest surface is the built-in **Model Context Protocol** server.\n\nMCP exposes every Easy API method as a discoverable tool that AI agents (Claude, Cursor, Windsurf, custom agents) can call directly — no manual HTTP wiring needed.\n\n### Quick start\n\n```bash\nnpx @open-wa\u002Fwa-automate --port 8080 --api-key \"your-secure-key\" --mcp\n```\n\nThen point your MCP client at:\n\n```text\nhttp:\u002F\u002Flocalhost:8080\u002Fmcp\n```\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"open-wa\": {\n      \"url\": \"http:\u002F\u002Flocalhost:8080\u002Fmcp\",\n      \"headers\": {\n        \"X-API-Key\": \"your-secure-key\"\n      }\n    }\n  }\n}\n```\n\n### Cursor \u002F Windsurf\n\nAdd a new MCP server with the URL `http:\u002F\u002Flocalhost:8080\u002Fmcp` and include `X-API-Key` in headers.\n\n### How it works\n\n- Uses the **Streamable HTTP** transport (single endpoint, no separate SSE\u002Fmessages paths)\n- Tools are generated from the schema registry — same methods as the HTTP API\n- **API key required** on every request (same key as Easy API)\n- Session readiness is enforced — tools block until the session is fully connected\n- Dashboard: shows connection status, configuration copy-paste snippets (Claude\u002FCursor), and live tool details at `http:\u002F\u002Flocalhost:8080\u002Fdashboard\u002Fmcp`\n\n### Configuration\n\n```json\n{\n  \"apiKey\": \"your-secure-key\",\n  \"mcp\": {\n    \"enabled\": true,\n    \"path\": \"\u002Fmcp\",\n    \"exposeToolsMeta\": true\n  }\n}\n```\n\n### Security boundary\n\nMCP is an **Easy API-only** feature. It is not available through `createClient()`. The API key is mandatory — MCP refuses to start without one. Discovery (tool listing) and execution both require authentication.\n\n### Without MCP\n\nIf you prefer HTTP, give your agent the Easy API docs surface instead:\n\n- `http:\u002F\u002Flocalhost:8080\u002Fapi-docs\u002F`\n- `http:\u002F\u002Flocalhost:8080\u002Fmeta\u002Fswagger.json`\n- `http:\u002F\u002Flocalhost:8080\u002Fmeta\u002Fpostman.json`\n\n## Documentation map\n\nThe current docs in this repo are organized around real usage modes. Start with:\n\n- **Easy API quick start**: https:\u002F\u002Fdocs.openwa.dev\u002Fdocs\u002Fgetting-started\u002Feasy-api\n- **Custom code**: https:\u002F\u002Fdocs.openwa.dev\u002Fdocs\u002Fgetting-started\u002Fcustom-code\n- **Socket Client**: https:\u002F\u002Fdocs.openwa.dev\u002Fdocs\u002Fclient-and-integrations\u002Fsocket-client\n- **Cloudflare Session Proxy**: https:\u002F\u002Fdocs.openwa.dev\u002Fdocs\u002Fclient-and-integrations\u002Fcf-proxy\n- **Configuration and CLI**: https:\u002F\u002Fdocs.openwa.dev\u002Fdocs\u002Fguides\u002Fconfiguration-and-cli\n- **Chatwoot**: https:\u002F\u002Fdocs.openwa.dev\u002Fdocs\u002Fclient-and-integrations\u002Fchatwoot\n- **Core reference**: https:\u002F\u002Fdocs.openwa.dev\u002Fdocs\u002Freference\u002Fcore\n\n## Running this repo locally\n\nIf you want to work on the monorepo itself:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fopen-wa\u002Fwa-automate-nodejs.git\ncd wa-automate-nodejs\npnpm install\npnpm build\n```\n\nUseful root scripts:\n\n```bash\npnpm dev\npnpm test\npnpm lint\npnpm typecheck\n```\n\n## Support\n\nIf you need help, paid support, or consulting:\n\n| Description | Link |\n| --- | --- |\n| Documentation | https:\u002F\u002Fdocs.openwa.dev |\n| Discord | https:\u002F\u002Fdiscord.gg\u002Fdnpp72a |\n| Get a license key | https:\u002F\u002Fopenwa.page.link\u002Fkey |\n| Donate or book 1 hour consult | [![Buy me a coffee][buymeacoffee-shield]][buymeacoffee] |\n| Per-minute consulting | \u003Ca href=\"http:\u002F\u002Fotechie.com\u002Fsmashah\">\u003Cimg src=\"https:\u002F\u002Fapi.otechie.com\u002Fconsultancy\u002Fsmashah\u002Fbadge.svg\" alt=\"Consulting\"\u002F>\u003C\u002Fa> |\n| Hire me | [![Consulting Request][consult-shield]][consult] |\n\n## License\n\n[Hippocratic + Do Not Harm Version 1.0](.\u002FLICENSE.md)\n\n## Legal\n\nThis code is in no way affiliated with, authorized, maintained, sponsored, or endorsed by WhatsApp or any of its affiliates or subsidiaries. This is independent and unofficial software.\n\n## Cryptography notice\n\nThis distribution includes cryptographic software. Depending on where you live, there may be restrictions on the import, possession, use, or re-export of encryption software. Check your local laws before using it. See [http:\u002F\u002Fwww.wassenaar.org\u002F](http:\u002F\u002Fwww.wassenaar.org\u002F) for more information.\n\nThe U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms. The form and manner of this distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.\n\n[buymeacoffee-shield]: https:\u002F\u002Fwww.buymeacoffee.com\u002Fassets\u002Fimg\u002Fguidelines\u002Fdownload-assets-sm-2.svg\n[buymeacoffee]: https:\u002F\u002Fwww.buymeacoffee.com\u002Fsmashah\n[consult-shield]: https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FRequire%20Paid%20Support%20or%20Consulting%3F-Click%20Here-blue?style=for-the-badge&logo=paypal\n[consult]: mailto:shah@openwa.dev?subject=WhatsApp%20Consulting\n","open-wa\u002Fwa-automate-nodejs 是一个用于创建具有高级功能的聊天机器人的可靠工具。它基于 TypeScript 构建，支持通过 Node.js 运行时将 WhatsApp 账号转化为 API 接口，并提供多种自动化和扩展方式。核心功能包括通过 CLI 快速启动 API、连接其他应用至运行时、直接嵌入到 Node.js 代码中以及添加插件和集成。该项目适用于需要通过 WhatsApp 实现自动化客户服务、消息推送等场景的企业和个人开发者。注意，当前版本 5 仍处于 alpha 阶段，建议在生产环境中使用稳定版 4.76.0。","2026-06-11 03:27:43","top_topic"]