{"id":48373609,"url":"https://github.com/phoscoder/wa-cloud-api","last_synced_at":"2026-04-05T17:42:52.122Z","repository":{"id":37718137,"uuid":"494984125","full_name":"phoscoder/wa-cloud-api","owner":"phoscoder","description":"Is an unofficial Javascript  wrapper for the Whatsapp Cloud API","archived":false,"fork":false,"pushed_at":"2025-12-14T19:13:43.000Z","size":152,"stargazers_count":28,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-05T17:42:45.988Z","etag":null,"topics":["api-wrapper","typescript","whatsapp-cloud-api"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phoscoder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2022-05-22T06:59:48.000Z","updated_at":"2026-01-06T14:40:38.000Z","dependencies_parsed_at":"2022-08-17T00:30:21.400Z","dependency_job_id":null,"html_url":"https://github.com/phoscoder/wa-cloud-api","commit_stats":null,"previous_names":["phoscoder/wa-cloud-api"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/phoscoder/wa-cloud-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoscoder%2Fwa-cloud-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoscoder%2Fwa-cloud-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoscoder%2Fwa-cloud-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoscoder%2Fwa-cloud-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phoscoder","download_url":"https://codeload.github.com/phoscoder/wa-cloud-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phoscoder%2Fwa-cloud-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31444702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["api-wrapper","typescript","whatsapp-cloud-api"],"created_at":"2026-04-05T17:42:51.571Z","updated_at":"2026-04-05T17:42:52.092Z","avatar_url":"https://github.com/phoscoder.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# \u003cimg src=\"https://upload.wikimedia.org/wikipedia/commons/6/6b/WhatsApp.svg\" alt=\"WhatsApp\" width=\"30\" height=\"30\"\u003e [Whatsapp Cloud API](https://npmjs.com/package/@phoscoder/whatsapp-cloud-api)\n\n[![Made in Zimbabwe🇿🇼](https://img.shields.io/badge/ported%20in-zimbabwe%20%F0%9F%87%BF%F0%9F%87%BC-blue)](https://github.com/phoscoder)\n![NPM](https://img.shields.io/npm/l/@phoscoder/whatsapp-cloud-api)\n![npm](https://img.shields.io/npm/v/@phoscoder/whatsapp-cloud-api)\n![npm](https://img.shields.io/npm/dw/@phoscoder/whatsapp-cloud-api)\n\n\nUnofficial Javascript wrapper to [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api). It was first ported from [heyoo](https://github.com/Neurotech-HQ/heyoo) but now I will be maintaining it and adding more features.\n\n## Features supported\n\n✅ Sending messages  \u003cbr\u003e\n✅ Sending  Media (images, audio, video and documents) \u003cbr\u003e\n✅ Sending location \u003cbr\u003e\n✅ Sending interactive buttons \u003cbr\u003e\n✅ Sending template messages \u003cbr\u003e\n✅ Get templates \u003cbr\u003e\n\n## Getting started\n\nTo get started with **whatsapp-cloud-api**, you have to firstly install the libary either directly or using *npm*.\n\n### Installing from npm\n\n```bash\n# For Windows, Linux \u0026 Mac\n\nnpm install @phoscoder/whatsapp-cloud-api\n```\n\n## Setting up\n\nTo get started using this package, you will need `**Access Token**`, `**Phone Number ID**` and `**Whatsapp Business Account ID**` which you can get by from [Facebook Developer Portal](https://developers.facebook.com/)\n\nHere are steps to follow for you to get started\n\n1. [Go to your apps](https://developers.facebook.com/apps)\n2. [create an app](https://developers.facebook.com/apps/create/)\n3. Select Bussiness \u003e\u003e Bussiness\n4. It will prompt you to enter basic app informations\n5. It will ask you to add products to your app\n    a. Add WhatsApp Messenger\n6. Right there you will see a your **Access Token**, **Whatsapp Business Account ID** and **Phone Number ID** and its phone_number_id\n7. Lastly verify the number you will be using for testing on the **To** field.\n\nOnce you're follow the above procedures, now you're ready to start hacking with the Wrapper.\n\n## Authentication\n\nHere how you authenticate your application, you need to specify two things the `\u003caccess token\u003e`, `\u003cphone number id\u003e` and `\u003cwhatsapp business account id\u003e` of your test number\n\n```javascript\nimport {WhatsApp} from '@phoscoder/whatsapp-cloud-api'\nlet messenger = new WhatsApp(\n    '\u003caccess token\u003e',  \n    '\u003cphone number id\u003e',\n    '\u003cwhatsapp business account id\u003e'\n)\n```\n\nOnce you have authenticated your app, now you can start using the above mentioned feature as shown above;\n\n## Sending Messanges\n\nHere how to send messages;\n\n```javscript\nmessenger.sendMessage('Your message ', 'Mobile eg: 263757xxxxx')\n```\n\n### Example\n\nHere an example\n\n```javascript\nmessenger.sendMessage('Hi there just testiing', '263757902132')\n```\n\n## Sending Images\n\nWhen sending media(image, video, audio, gif and document ), you can either specify a link containing  the media or specify object id, you can do this using the same method.\n\nBy default all media methods assume you're sending link containing media but you can change this by specifying the ```link=False```.\n\nHere an example;\n\n```javascript\nmessenger.sendImage(\n        \"https://i.imgur.com/Fh7XVYY.jpeg\",\n        \"263757xxxxxx\",\n)\n```\n\n## Sending Video\n\nHere an example;\n\n```javascript\n\nmessenger.sendVideo(\n        \"https://www.youtube.com/watch?v=K4TOrB7at0Y\",\n        \"263757xxxxxx\",\n)\n```\n\n## Sending Audio\n\nHere an example;\n\n```javascript\nmessenger.sendAudio(\n        \"https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3\",\n        \"263757xxxxxx\",\n)\n```\n\n## Sending Document\n\nHere an example;\n\n```javascript\nmessenger.sendDocument(\n        \"http://www.africau.edu/images/default/sample.pdf\",\n        \"263757xxxxxx\",      // Recipient ID\n        \"sample.pdf\",        // File Name\n        \"Sample Document\"    // Caption\n)\n```\n\n## Sending Location\n\nHere an example;\n\n```javascript\nmessenger.sendLocation(\n        lat=1.29,\n        long=103.85,\n        name=\"Singapore\",\n        address=\"Singapore\",\n        recipient_id=\"263757xxxxxx\",\n    )\n```\n\n## Sending Interactive buttons\n\nHere an example;\n\n```javascript\n\nconst button = {\n    \"header\": \"Header Testing\",\n    \"body\": \"Body Testing\",\n    \"footer\": \"Footer Testing\",\n    \"action\": {\n        \"button\": \"Button Testing\",\n        \"sections\": [\n            {\n                \"title\": \"iBank\",\n                \"rows\": [\n                    {\"id\": \"row 1\", \"title\": \"Send Money\", \"description\": \"\"},\n                    {\n                        \"id\": \"row 2\",\n                        \"title\": \"Withdraw money\",\n                        \"description\": \"\",\n                    },\n                ],\n            }\n        ],\n    },\n}\n\nmessenger.sendButton(\n        button,\n        \"263757xxxxxx\"\n)\n```\n\n## Sending a Template Messages\n\nHere how to send a pre-approved template message;\n\n```javascript\nmessenger.sendTemplate(\"hello_world\", \"263757xxxxxx\")\n```\n\n## Sending a Template Messages with Components\nYou can now specify components like this\n\n```javascript\nlet components = [ \n  // Your components here\n]\n\nmessenger.sendTemplate(\"hello_world\", \"263757xxxxxx\", components)\n```\n\nFor moreabout components: https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates\n\n## Webhook\n\nWebhooks are useful incase you're wondering how to respond to incoming message send by user, but I have created a [starter webhook](https://github.com/phoscoder/whatsapp-cloud-api/blob/main/src/hook.ts) which you can then customize it according to your own plans.\n\nTo learn more about webhook and how to configure in your Facebook developer dashboard please [have a look here](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks).\n\n\n\n### Notification Payload Structure\n\nThis is the structure of the notifications that you will recieve from Whatsapp when a certain event is triggered\n\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e Example Notification Payload \u003c/td\u003e \u003ctd\u003e Nested Structure of the Payload \u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```bash\n{\n  \"object\": \"whatsapp_business_account\",\n  \"entry\": [{\n    \"id\": \"WHATSAPP-BUSINESS-ACCOUNT-ID\",\n    \"changes\": [{\n      \"value\": {\n         \"messaging_product\": \"whatsapp\",\n         \"metadata\": {\n           \"display_phone_number\": \"PHONE-NUMBER\",\n           \"phone_number_id\": \"PHONE-NUMBER-ID\"\n         },\n      # Additional arrays and objects\n         \"contacts\": [{...}]\n         \"errors\": [{...}]\n         \"messages\": [{...}]\n         \"statuses\": [{...}]\n      },\n      \"field\": \"messages\"\n    }]\n  }]\n}\n```\n\u003c/td\u003e\n\u003ctd\u003e\n    \n\u003cimage src=\"https://scontent.fhre1-1.fna.fbcdn.net/v/t39.8562-6/279222632_734660030860914_6012822392536302447_n.png?_nc_cat=102\u0026ccb=1-7\u0026_nc_sid=6825c5\u0026_nc_ohc=6JRg8jSurMkAX96mfPU\u0026_nc_ht=scontent.fhre1-1.fna\u0026oh=00_AT-ijPsejf2Ys89V08c7qqC3I8wy1ppmk5RedBKakjDe8Q\u0026oe=628FFFB6\"\u003e\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\n\n### Recieving notifications (Method #1 \u003e Inbuilt server)\nTo receive notifications such as customer messages, alerts and other callbacks from WhatsApp you can start a server that listens and handles notifications from Whatsapp\n\n```javascript\nimport { Server } from '@phoscoder/whatsapp-cloud-api'\nimport 'dotenv/config'\n\nlet notificationsServer = new Server(\n    process.env.VERIFY_TOKEN,\n    process.env.LISTEN_PORT,\n)\n\nlet app = notificationsServer.start(async (rawData ,processedPayload) =\u003e {\n  // Do your stuff here\n  \n  if (processedPayload.type == \"messages\") {\n    let messages = processedPayload.getMessages()\n    let metadata = processedPayload.getMetadata()\n    let contacts = processedPayload.getContacts()\n  \n  if (processedPayload.type == \"contacts\") {\n    let contacts = processedPayload.getContacts()\n  \n  if (processedPayload.type == \"status\") {\n    let status = processedPayload.getStatuses()\n\n  // Do other stuff here\n})\n```\n\n`rawData` -\u003e This is raw data straight from WhatsApp\n`processedPayload` -\u003e This is an object of `ProcessPayload` it gives access to the raw_data plus helper methods\n\n\u003e [!NOTE] \n\u003e Beginners should work more with processed since it saves you time and minimizes errors\n\n**Tip:** You can refactor it to look more presentable:\n\n```javascript\nimport handleNotifications from 'path/to/file'\n\nlet app = notificationServer.start(handleNotifications)\n```\n### Recieving notifications (Method #2 \u003e Existing server)\nTo receive notifications such as customer messages, alerts and other callbacks from WhatsApp on an existing server, take the following steps\n\n```javascript\nimport { \n  Server, \n  NotificationPayload, \n  ProcessPayload, \n  VerifyWebhookToken } from '@phoscoder/whatsapp-cloud-api'\n\nimport dotenv from 'dotenv'\ndotenv.config()\n\nconst VERIFY_TOKEN = process.env.VERIFY_TOKEN\n\n // For webhook verification\n app.get(\"/\", async (req: Request, res:Response) =\u003e {      \n      const server = new Server(VERIFY_TOKEN)\n      let res = server.verifyWebhookToken(req.query as Record\u003cstring, any\u003e)\n      res.send(res)\n  })\n\n  // For incoming notifications\n  app.post(\"/\", async (req: Request, res:Response) =\u003e {\n      let data: NotificationPayload = req.body\n  \n      let processedPayload = new ProcessPayload(data)\n      \n      // Do your stuff here\n      if (processedPayload.type == \"messages\") {\n        let messages = processedPayload.getMessages()\n        let metadata = processedPayload.getMetadata()\n        let contacts = processedPayload.getContacts()\n      \n      if (processedPayload.type == \"contacts\") {\n        let contacts = processedPayload.getContacts()\n      \n      if (processedPayload.type == \"status\") {\n        let status = processedPayload.getStatuses()\n\n      return res.json(\"Notification recieved!\")\n  })\n```\n\n\n### Getting media links \n\nTo retrive actual media link\n\n```javascript\nlet message = processedPayload.getMessages()[0]\nlet mediaData = await messenger.getMedia(message.image.id)\n```\n\n\u003e [!NOTE]\n\u003e The URL you get is only available for a 5 minutes, so you may need to download it and store it somewhere, or use it as quick as possible\n\n\nFor more info check [Notification Payload Reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components) and [Notification Payload Examples](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/payload-examples)\n\n## Debugging\n\nIn cases where you want to see the full response and all its data set debug to true like this\n\n```js\nimport { WhatsApp } from '@phoscoder/whatsapp_cloud_api'\n...\n...\n...\nconst client = new WhatsApp(\"\u003ctoken\u003e\", \"\u003cphone_number_id\u003e\", true)\n```\n\nOR this \n\n```js \nclient.debug = true \n```\n\n\n## Issues\n\nIf you will face any issue with the usage of this package please raise one so as we can quickly fix it as soon as possible;\n\n## Contributing\n\nThis is an opensource project under ```MIT License``` so any one is welcome to contribute from typo, to source code to documentation, ```JUST FORK IT```.\n\n## All the credit\n\n1. [kalebu](https://github.com/Kalebu)\n2. [takunda](https://github.com/takumade)\n3. Contribute to get added here\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphoscoder%2Fwa-cloud-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphoscoder%2Fwa-cloud-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphoscoder%2Fwa-cloud-api/lists"}