{"id":15150515,"url":"https://github.com/tawn33y/whatsapp-cloud-api","last_synced_at":"2025-09-29T19:30:52.333Z","repository":{"id":37043251,"uuid":"497562656","full_name":"tawn33y/whatsapp-cloud-api","owner":"tawn33y","description":"A Node.js library for creating bots and sending/receiving messages using the Whatsapp Cloud API.","archived":true,"fork":false,"pushed_at":"2024-07-25T04:48:20.000Z","size":984,"stargazers_count":189,"open_issues_count":0,"forks_count":52,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-01-05T08:51:57.213Z","etag":null,"topics":["api","bot","bot-api","bot-framework","business-api","chatbot","cloud","cloud-api","nodejs","whatsapp","whatsapp-api","whatsapp-bot","whatsapp-business","whatsapp-business-api","whatsapp-cloud","whatsapp-cloud-api"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/whatsapp-cloud-api","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tawn33y.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2022-05-29T10:52:14.000Z","updated_at":"2024-11-08T22:26:53.000Z","dependencies_parsed_at":"2024-07-25T05:46:11.766Z","dependency_job_id":"2e5cc327-12ae-4aaf-8426-072ae7b1647a","html_url":"https://github.com/tawn33y/whatsapp-cloud-api","commit_stats":{"total_commits":81,"total_committers":2,"mean_commits":40.5,"dds":0.07407407407407407,"last_synced_commit":"c3158fe94dd47f42fb37ab09b02e25d1fee10912"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tawn33y%2Fwhatsapp-cloud-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tawn33y%2Fwhatsapp-cloud-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tawn33y%2Fwhatsapp-cloud-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tawn33y%2Fwhatsapp-cloud-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tawn33y","download_url":"https://codeload.github.com/tawn33y/whatsapp-cloud-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234510956,"owners_count":18844613,"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","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":["api","bot","bot-api","bot-framework","business-api","chatbot","cloud","cloud-api","nodejs","whatsapp","whatsapp-api","whatsapp-bot","whatsapp-business","whatsapp-business-api","whatsapp-cloud","whatsapp-cloud-api"],"created_at":"2024-09-26T14:20:47.389Z","updated_at":"2025-09-29T19:30:47.037Z","avatar_url":"https://github.com/tawn33y.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# whatsapp-cloud-api\n\n`whatsapp-cloud-api` is a Node.js library for creating bots and sending/receiving messages using the [Whatsapp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/).\n\nContains built-in Typescript declarations.\n\n[![run tests, lint, build](https://github.com/tawn33y/whatsapp-cloud-api/actions/workflows/tests.yml/badge.svg)](https://github.com/tawn33y/whatsapp-cloud-api/actions/workflows/tests.yml)\n[![npm publish](https://github.com/tawn33y/whatsapp-cloud-api/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/tawn33y/whatsapp-cloud-api/actions/workflows/npm-publish.yml)\n![npm](https://img.shields.io/npm/v/whatsapp-cloud-api)\n![npm bundle size](https://img.shields.io/bundlephobia/min/whatsapp-cloud-api)\n![npm](https://img.shields.io/npm/dw/whatsapp-cloud-api)\n\n\u003chr \u003e\n\n## ℹ️ Status\n\nThis project is now **Archived**. Please [read more here](https://github.com/tawn33y/whatsapp-cloud-api/issues/65).\n\n\u003chr\u003e\n\n## Install\n\nUsing npm:\n\n```bash\nnpm i whatsapp-cloud-api\n```\n\nUsing yarn:\n\n```bash\nyarn add whatsapp-cloud-api\n```\n\n## Usage\n\n```js\nimport { createBot } from 'whatsapp-cloud-api';\n// or if using require:\n// const { createBot } = require('whatsapp-cloud-api');\n\n(async () =\u003e {\n  try {\n    // replace the values below\n    const from = 'YOUR_WHATSAPP_PHONE_NUMBER_ID';\n    const token = 'YOUR_TEMPORARY_OR_PERMANENT_ACCESS_TOKEN';\n    const to = 'PHONE_NUMBER_OF_RECIPIENT';\n    const webhookVerifyToken = 'YOUR_WEBHOOK_VERIFICATION_TOKEN';\n\n    // Create a bot that can send messages\n    const bot = createBot(from, token);\n\n    // Send text message\n    const result = await bot.sendText(to, 'Hello world');\n\n    // Start express server to listen for incoming messages\n    // NOTE: See below under `Documentation/Tutorial` to learn how\n    // you can verify the webhook URL and make the server publicly available\n    await bot.startExpressServer({\n      webhookVerifyToken,\n    });\n\n    // Listen to ALL incoming messages\n    // NOTE: remember to always run: await bot.startExpressServer() first\n    bot.on('message', async (msg) =\u003e {\n      console.log(msg);\n\n      if (msg.type === 'text') {\n        await bot.sendText(msg.from, 'Received your text message!');\n      } else if (msg.type === 'image') {\n        await bot.sendText(msg.from, 'Received your image!');\n      }\n    });\n  } catch (err) {\n    console.log(err);\n  }\n})();\n```\n\n## Documentation\n\n- [API Reference](./API.md).\n- [Tutorial](./TUTORIAL.md) for a step-by-step on how to get everything set up.\n\n## Examples\n\nSending other message types ([read more in API reference](./API.md#api-reference)):\n\n```js\n// Send image\nconst result = await bot.sendImage(to, 'https://picsum.photos/200/300', {\n  caption: 'Random jpg',\n});\n\n// Send location\nconst result = await bot.sendLocation(to, 40.7128, -74.0060, {\n  name: 'New York',\n});\n\n// Send template\nconst result = await bot.sendTemplate(to, 'hello_world', 'en_us');\n```\n\nCustomized express server ([read more below](#2-handling-incoming-messages)):\n\n```js\nimport cors from 'cors';\n\n// Create bot...\nconst bot = createBot(...);\n\n// Customize server\nawait bot.startExpressServer({\n  webhookVerifyToken: 'my-verification-token',\n  port: 3000,\n  webhookPath: `/custom/webhook`,\n  useMiddleware: (app) =\u003e {\n    app.use(cors()),\n  },\n});\n```\n\nListening to other message types ([read more in API reference](./API.md#onevent-cb-message--void)):\n\n```js\nconst bot = createBot(...);\n\nawait bot.startExpressServer({ webhookVerifyToken });\n\n// Listen to incoming text messages ONLY\nbot.on('text', async (msg) =\u003e {\n  console.log(msg);\n  await bot.sendText(msg.from, 'Received your text!');\n});\n\n// Listen to incoming image messages ONLY\nbot.on('image', async (msg) =\u003e {\n  console.log(msg);\n  await bot.sendText(msg.from, 'Received your image!');\n});\n```\n\n## Notes\n\n### 1. Verifying your Webhook URL\n\nBy default, the endpoint for whatsapp-related requests will be: `/webhook/whatsapp`.\nThis means that locally, your URL will be: `http://localhost/webhook/whatsapp`.\n\nYou can use a reverse proxy to make the server publicly available. An example of this is [ngrok](https://ngrok.com/download). \n\nYou can [read more on the Tutorial](./TUTORIAL.md#3-setting-up-ngrok).\n\n### 2. Handling incoming messages\n\nThe implementation above creates an express server for you through which it listens to incoming messages. There may be plans to support other types of server in future (PRs are welcome! :)).\n\nYou can change the port as follows:\n\n```js\nawait bot.startExpressServer({\n  port: 3000,\n});\n```\n\nBy default, all requests are handled by the `POST|GET /webhook/whatsapp` endpoint. You can change this as below:\n\n```js\nawait bot.startExpressServer({\n  webhookPath: `/custom/webhook`,\n});\n```\n\n**Note:** Remember the leading `/`; i.e. don't use `custom/whatsapp`; instead use `/custom/whatsapp`.\n\nIf you are already running an express server in your application, you can avoid creating a new one by using it as below:\n\n```js\n// your code...\nimport express from 'express';\nconst app = express();\n\n...\n\n// use the `app` variable below:\nawait bot.startExpressServer({\n  app,\n});\n```\n\nTo add middleware:\n\n```js\nimport cors from 'cors';\n\nawait bot.startExpressServer({\n  useMiddleware: (app) =\u003e {\n    app.use(cors()),\n  },\n});\n```\n\nFull customized setup:\n\n```js\nimport cors from 'cors';\n\nawait bot.startExpressServer({\n  webhookVerifyToken: 'my-verification-token',\n  port: 3000,\n  webhookPath: `/custom/webhook`,\n  useMiddleware: (app) =\u003e {\n    app.use(cors()),\n  },\n});\n```\n\n### 3. `on()` listener\n\nThis library uses a single process pubsub, which means that it won't work well if you're deploying on multi-instance clusters, e.g. distributed Kubernetes clusters. In future, there may be plans to export/support a pubsub reference which can be stored in extenal storage, e.g. redis (PRs are welcome! :)).\n\n## Development\n\n```bash\n# install npm modules\nnpm i\n\n# eslint\nnpm run lint\n\n# typescript check\nnpm run ts-check\n\n# test\n## Read 'Local Testing' below before running this\nnpm t\n\n# build\nnpm run build\n```\n\n### Local Testing\n\nCreate a .env file in the root of your project:\n\n```txt\nFROM_PHONE_NUMBER_ID=\"\"\nACCESS_TOKEN=\"\"\nVERSION=\"\"\nTO=\"\"\nWEBHOOK_VERIFY_TOKEN=\"\"\nWEBHOOK_PATH=\"\"\n```\n\n### Attribution\n\nLibrary API inspired by [node-telegram-bot-api](https://github.com/yagop/node-telegram-bot-api/blob/release/doc/api.md).\n\n## Pull Requests\n\nAny and all PRs are open.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftawn33y%2Fwhatsapp-cloud-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftawn33y%2Fwhatsapp-cloud-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftawn33y%2Fwhatsapp-cloud-api/lists"}