{"id":31051522,"url":"https://github.com/khrasedul-dev/jswhatsappbot","last_synced_at":"2026-01-20T17:37:16.147Z","repository":{"id":314331042,"uuid":"1054891338","full_name":"khrasedul-dev/jswhatsappbot","owner":"khrasedul-dev","description":"A modern telegraf-style framework for WhatsApp bots.","archived":false,"fork":false,"pushed_at":"2025-09-11T19:39:19.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-11T22:30:26.579Z","etag":null,"topics":["bot","jswhatsappbot","telegraf","whatsapp","whatsapp-bot"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/jswhatsappbot","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/khrasedul-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-11T13:25:01.000Z","updated_at":"2025-09-11T19:39:22.000Z","dependencies_parsed_at":"2025-09-11T22:30:30.126Z","dependency_job_id":"0024f9b1-d169-4174-892f-8570b4046dae","html_url":"https://github.com/khrasedul-dev/jswhatsappbot","commit_stats":null,"previous_names":["khrasedul-dev/jswhatsappbot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/khrasedul-dev/jswhatsappbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khrasedul-dev%2Fjswhatsappbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khrasedul-dev%2Fjswhatsappbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khrasedul-dev%2Fjswhatsappbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khrasedul-dev%2Fjswhatsappbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khrasedul-dev","download_url":"https://codeload.github.com/khrasedul-dev/jswhatsappbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khrasedul-dev%2Fjswhatsappbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275160370,"owners_count":25415767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","jswhatsappbot","telegraf","whatsapp","whatsapp-bot"],"created_at":"2025-09-15T00:27:19.840Z","updated_at":"2025-09-16T01:02:23.406Z","avatar_url":"https://github.com/khrasedul-dev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"A **Telegraf-inspired framework** for building **WhatsApp Cloud API bots** with modern **scene** and **session** management.\n\n## 💖 Support My Work\n\nIf you enjoy my projects and want to support me, you can donate using **crypto** 🚀\n\n---\n\n### 🌍 Wallet Addresses\n\n| Coin | Network | Address |\n|------|---------|---------|\n| 🟠 **Bitcoin (BTC)** | Bitcoin | `1PouA4hPvM4sgg26RbbevBuG3JVF2yGiTt` |\n| 🔵 **Ethereum (ETH)** | ERC20 | `0x35e743344347b02e0071e8ec2a9850ec4fc879f2` |\n| 🟢 **Tether (USDT)** | TRC20 | `TWUbLudtqA65r6tFXrhBigVxgH22GikMct` |\n| 🟢 **Tether (USDT)** | ERC20 | `0x35e743344347b02e0071e8ec2a9850ec4fc879f2` |\n\n---\n\n[![Donate Bitcoin](https://img.shields.io/badge/Bitcoin-Donate-orange?logo=bitcoin\u0026style=for-the-badge)](bitcoin:1PouA4hPvM4sgg26RbbevBuG3JVF2yGiTt)\n[![Donate Ethereum](https://img.shields.io/badge/Ethereum-Donate-blue?logo=ethereum\u0026style=for-the-badge)](ethereum:0x35e743344347b02e0071e8ec2a9850ec4fc879f2)\n[![Donate USDT](https://img.shields.io/badge/USDT-Donate-green?logo=tether\u0026style=for-the-badge)](https://tronscan.org/#/address/TWUbLudtqA65r6tFXrhBigVxgH22GikMct)\n\n---\n\n✨ Thank you for your support — it really means a lot! 🙏\n\n\n\n## Features\n\n- Step-by-step **scene system** (Wizard-like)\n- In-memory and file-based **session storage**\n- **Middleware-based architecture**\n- Simple API for **commands**, **actions**, and **media**\n- Persistent sessions (optional)\n- Clean, modern codebase\n- Reply buttons and keyboards\n- Media support: images, documents, audio, video\n- Global error handling\n\n## Installation\n\n```bash\nnpm install jswhatsappbot\n```\n\n\n## API\n### Default webhook listen\n- `https://\u003cyour site\u003e/webhook`\n\n### WhatsAppBot\n\n- `command(cmd, fn)` — Register a command handler\n- `hears(pattern, fn)` — Register a text/button handler\n- `use(middleware)` — Add middleware\n- `start(port)` — Start the bot server\n- `catch(fn)` — Global error handler\n\n### Scene System\n\n- `Scene(name, steps[])` — Create a scene\n- `SceneManager()` — Manage and register scenes\n- `scenes.register(scene)` — Register a scene\n- `scenes.middleware()` — Scene middleware\n- `scenes.enter('sceneName')` — Enter a scene\n\n### Session Middleware\n\n- `session({ type: 'file' })` — Use file-based session (default is in-memory)\n\n### Markup (Buttons, Keyboards, Media)\n\nImport Markup:\n\n```js\nimport { Markup } from 'jswhatsappbot'\n```\n\n#### Reply Buttons (Keyboard)\n\n```js\nawait ctx.reply(\n  Markup.keyboard('Choose an option:', [[{ text: 'Yes' }, { text: 'No' }]])\n)\n```\n\n### Handle button actions:\n\n```js\nbot.hears('Yes', async (ctx) =\u003e {\n  await ctx.reply('You clicked Yes!')\n})\nbot.hears('No', async (ctx) =\u003e {\n  await ctx.reply('You clicked No!')\n})\n```\n\n#### Media Replies\n\n```js\nawait ctx.replyWithPhoto('https://example.com/photo.jpg')\nawait ctx.replyWithDocument('https://example.com/file.pdf')\nawait ctx.replyWithAudio('https://example.com/audio.mp3')\nawait ctx.replyWithVideo('https://example.com/video.mp4')\n```\n\n### Multiple patterns\n\n```js\nbot.hears(['hi', 'hello', /test/], handler)\nbot.command(['/start', '/help'], handler)\n```\n\n### Example: Registration Scene\n\n```js\nimport WhatsAppBot, {\n  Markup,\n  session,\n  Scene,\n  SceneManager,\n} from 'jswhatsappbot'\n\nconst bot = new WhatsAppBot({\n  accessToken: process.env.WHATSAPP_ACCESS_TOKEN,\n  verifyToken: process.env.WHATSAPP_VERIFY_TOKEN,\n  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID,\n})\n\nconst registrationScene = new Scene('registration', [\n  async (ctx) =\u003e {\n    await ctx.reply('Welcome to registration! What is your first name?')\n  },\n  async (ctx) =\u003e {\n    if (!ctx.text) {\n      await ctx.reply('Please enter your first name.')\n      return false\n    }\n    ctx.session.firstName = ctx.text\n    await ctx.reply('What is your last name?')\n  },\n  async (ctx) =\u003e {\n    if (!ctx.text) {\n      await ctx.reply('Please enter your last name.')\n      return false\n    }\n    ctx.session.lastName = ctx.text\n    await ctx.reply('What is your email address?')\n  },\n  async (ctx) =\u003e {\n    if (!ctx.text || !/\\S+@\\S+\\.\\S+/.test(ctx.text)) {\n      await ctx.reply('Please enter a valid email address.')\n      return false\n    }\n    ctx.session.email = ctx.text\n    await ctx.reply(\n      `Registration complete!\\nFirst Name: ${ctx.session.firstName}\\nLast Name: ${ctx.session.lastName}\\nEmail: ${ctx.session.email}`\n    )\n    await ctx.scene.leave(ctx)\n  },\n])\n\nconst scenes = new SceneManager()\nscenes.register(registrationScene)\n\nbot.use(session())\nbot.use(scenes.middleware())\n\nbot.command('/start', async (ctx) =\u003e {\n  await ctx.reply('Welcome! Type /registration to begin.')\n})\nbot.command('/registration', async (ctx) =\u003e {\n  await scenes.enter('registration')(ctx)\n})\n```\n\n## Event System\n\nHandle all incoming messages:\n\n```js\nbot.on('message', async (ctx) =\u003e {\n  // Runs for every incoming message\n  console.log('Received message:', ctx.text)\n})\n```\n\n## Example: Simple Bot\n\n```js\nimport 'dotenv/config'\nimport WhatsAppBot, { Markup, session, Scene, SceneManager } from '../index.js'\n\nconst bot = new WhatsAppBot({\n  accessToken: process.env.WHATSAPP_ACCESS_TOKEN,\n  verifyToken: process.env.WHATSAPP_VERIFY_TOKEN,\n  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID,\n})\n\nconst registrationScene = new Scene('registration', [\n  async (ctx) =\u003e {\n    await ctx.reply('Welcome to registration! What is your first name?')\n  },\n  async (ctx) =\u003e {\n    if (!ctx.text) {\n      await ctx.reply('Please enter your first name.')\n      return false\n    }\n    ctx.session.firstName = ctx.text\n    await ctx.reply('What is your last name?')\n  },\n  async (ctx) =\u003e {\n    if (!ctx.text) {\n      await ctx.reply('Please enter your last name.')\n      return false\n    }\n    ctx.session.lastName = ctx.text\n    await ctx.reply('What is your email address?')\n  },\n  async (ctx) =\u003e {\n    if (!ctx.text || !/\\S+@\\S+\\.\\S+/.test(ctx.text)) {\n      await ctx.reply('Please enter a valid email address.')\n      return false\n    }\n    ctx.session.email = ctx.text\n    await ctx.reply(\n      `Registration complete!\\nFirst Name: ${ctx.session.firstName}\\nLast Name: ${ctx.session.lastName}\\nEmail: ${ctx.session.email}`\n    )\n    await ctx.scene.leave(ctx)\n  },\n])\n\nconst scenes = new SceneManager()\nscenes.register(registrationScene)\n\nbot.use(session())\nbot.use(scenes.middleware())\n\nbot.command('/start', async (ctx) =\u003e {\n  await ctx.reply('Welcome! Type /registration to begin.')\n})\nbot.command('/registration', async (ctx) =\u003e {\n  await scenes.enter('registration')(ctx)\n})\n\nconst testPhotoUrl = 'https://www.w3schools.com/w3images/lights.jpg'\nconst testDocUrl =\n  'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'\nconst testAudioUrl =\n  'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3'\nconst testVideoUrl = 'https://www.w3schools.com/html/mov_bbb.mp4'\n\nbot.hears('/photo', async (ctx) =\u003e {\n  await ctx.replyWithPhoto(testPhotoUrl)\n  await ctx.reply(\n    Markup.keyboard('Choose an option:', [[{ text: 'Yes' }, { text: 'No' }]])\n  )\n})\n\nbot.hears('/keyboard', async (ctx) =\u003e {\n  await ctx.reply(\n    Markup.keyboard('Choose an option:', [\n      [{ text: 'Yes' }, { text: 'No' }, { text: 'test button' }],\n    ])\n  )\n})\n\nbot.hears('Yes', async (ctx) =\u003e {\n  await ctx.reply('You clicked Yes!')\n})\n\nbot.hears('No', async (ctx) =\u003e {\n  await ctx.reply('You clicked No!')\n})\n\nbot.on('message', async (ctx) =\u003e {\n  await ctx.reply('Echo: ' + ctx.text)\n})\n\nbot.start(3000)\n```\n\n## Custom Express Hosting\n\nYou can host whatsappjs with your own Express app:\n\n```js\nimport express from 'express'\nimport WhatsAppBot from 'jswhatsappbot'\n\nconst bot = new WhatsAppBot({\n  /* ...config... */\n})\n\nconst app = express()\napp.use(express.json())\n\n// Mount WhatsApp webhook route\napp.use('/webhook', bot.app)\n\n// Start your own server\napp.listen(3000, () =\u003e {\n  console.log('Custom Express server running on port 3000')\n})\n```\n\nDo not use `bot.start()` if you want full control over your Express server.\n\n## License\n\nMIT\n\n## Author\n\nKH Rasedul — [rasedul.dev@gmail.com](mailto:rasedul.dev@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhrasedul-dev%2Fjswhatsappbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhrasedul-dev%2Fjswhatsappbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhrasedul-dev%2Fjswhatsappbot/lists"}