{"id":14987139,"url":"https://github.com/daggieblanqx/whatsappcloudapi_wrapper","last_synced_at":"2025-10-24T22:36:56.478Z","repository":{"id":37561314,"uuid":"502716927","full_name":"DaggieBlanqx/whatsappcloudapi_wrapper","owner":"DaggieBlanqx","description":"An easy way to build Whatsapp Chatbots on top of the new Whatsapp Cloud API","archived":false,"fork":false,"pushed_at":"2024-11-25T03:04:32.000Z","size":150,"stargazers_count":141,"open_issues_count":19,"forks_count":67,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-10-07T05:45:13.227Z","etag":null,"topics":["chatbot","cloud","cloud-api","meta","sdk","whatsapp","whatsapp-api","whatsapp-bot","whatsapp-business","whatsapp-business-api","whatsapp-cloud","whatsapp-cloud-api","whatsapp-cloud-api-client"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DaggieBlanqx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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},"funding":{"github":null,"patreon":"daggieblanqx","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2022-06-12T20:08:26.000Z","updated_at":"2025-10-01T23:22:59.000Z","dependencies_parsed_at":"2024-01-16T10:12:12.289Z","dependency_job_id":"38a11813-c502-470b-a981-b40330b4119d","html_url":"https://github.com/DaggieBlanqx/whatsappcloudapi_wrapper","commit_stats":{"total_commits":135,"total_committers":10,"mean_commits":13.5,"dds":"0.18518518518518523","last_synced_commit":"779a8c200ea836afadfd6bfd0df134287eb8b190"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/DaggieBlanqx/whatsappcloudapi_wrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaggieBlanqx%2Fwhatsappcloudapi_wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaggieBlanqx%2Fwhatsappcloudapi_wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaggieBlanqx%2Fwhatsappcloudapi_wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaggieBlanqx%2Fwhatsappcloudapi_wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DaggieBlanqx","download_url":"https://codeload.github.com/DaggieBlanqx/whatsappcloudapi_wrapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaggieBlanqx%2Fwhatsappcloudapi_wrapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280878347,"owners_count":26406641,"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-10-24T02:00:06.418Z","response_time":73,"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":["chatbot","cloud","cloud-api","meta","sdk","whatsapp","whatsapp-api","whatsapp-bot","whatsapp-business","whatsapp-business-api","whatsapp-cloud","whatsapp-cloud-api","whatsapp-cloud-api-client"],"created_at":"2024-09-24T14:14:09.313Z","updated_at":"2025-10-24T22:36:56.433Z","avatar_url":"https://github.com/DaggieBlanqx.png","language":"JavaScript","funding_links":["https://patreon.com/daggieblanqx"],"categories":[],"sub_categories":[],"readme":"# whatsappcloudapi_wrapper 🎉\n\n\u003cimg src=\"https://img.shields.io/npm/v/whatsappcloudapi_wrapper\"\n    alt=\"Whatsapp Cloud API\"/\u003e\n\n\u003cimg src=\"https://img.shields.io/npm/dw/whatsappcloudapi_wrapper\"\n    alt=\"Whatsapp Cloud API\"/\u003e\n\u003cbr/\u003e\n\nThe \u003cb\u003eeasiest\u003c/b\u003e, most intuitive way for \u003cb\u003ebusinesses\u003c/b\u003e and \u003cb\u003edevelopers\u003c/b\u003e to start building on the \u003cb\u003eWhatsapp Cloud API\u003c/b\u003e.\n\n😻 Send a free-formatted text message to a recipient\n\n🗺 Send a Geo-location message to a recipient\n\n📃 Send a document to a recipient\n\n📷 Send an image to a recipient\n\n🎞 Send a video to a recipient\n\n🔉 Send an audio to a recipient\n\n🔙 Send a list of buttons to the recipient (max number of buttons allowed are 3)\n\n🛒 Send a list of radio buttons to a recipient (max number of radio buttons allowed are 10)\n\n🤙🏾 Send a contact to a recipient\n\n🔐 Generate a QR code which can be scanned by a recipient\n\n📖 Mark a message as read\n\n🎨🖌 Parse incoming messages\n\n\u003cimg src=\"./static_files/379234-whatsapp-cloud-api.jpeg\"\n    alt=\"Whatsapp Cloud API\"/\u003e\n\u003cbr/\u003e\n\n\u003c!-- ![npm bundle size](https://img.shields.io/bundlephobia/min/whatsappcloudapi_wrapper) --\u003e\n\n### Frequently Asked Questions:\n\n-   What is WhatsApp Cloud API? [Watch this 60seconds video](https://www.youtube.com/watch?v=LaHnC7emQNM) during the launch Whatsapp Cloud API.\n-   What is this package? This package is an unofficial and _open-source_ NodeJS wrapper around the official [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api).\n-   Why is this package useful? Because it allows you to use the WhatsApp Cloud API without having to write a lot of code.\n-   Can I use this package in my project? Yes, you can use it however you want.\n-   Can I contribute to this package? Yes, you can contribute to this package by creating a pull request.\n\n### Installation:\n\n-   To install this package in your project:\n-   Using NPM:\n\n```js\n        npm install whatsappcloudapi_wrapper\n```\n\n-   Using Yarn:\n\n```js\n        yarn add whatsappcloudapi_wrapper\n```\n\n# Usage:\n\n-   First import the package as follows:\n\n```js\nconst WhatsappCloudAPI = require('whatsappcloudapi_wrapper');\n```\n\n-   Then initialize the class as follows:\n\n```js\nconst Whatsapp = new WhatsappCloudAPI({\n    accessToken: 'Your access token here',\n    senderPhoneNumberId: 'Your sender phone number id here',\n    WABA_ID: 'Your Whatsapp Business Account id here',\n});\n```\n\n## Part 1: Outbound messages (From business to customers)\n\n#### Send a free-formatted text message to a recipient:\n\n```js\nawait Whatsapp.sendText({\n    message: 'Hello world',\n    recipientPhone: 'your recipient phone number here',\n});\n```\n\n    \u003e Quick Question:\n    - How does a recipient phone number look like?\n\n    \u003e Quick Answer:\n    - A recipient phone number is the international phone number of the recipient without the '+' prefix.\n    - For example, where a Kenyan phone number is '+254712345678' we would send the message to a recipientPhone 254712345678.\n    - For a phone number +15550253483 we would send the message to a recipientPhone 15550253483.\n    - For an US phone number +1 555-555-5555 we would send the message to a recipientPhone 5555555555.\n\n    Makes sense?\n\n#### Send a Geo-location message to a recipient:\n\n```js\nawait Whatsapp.sendLocation({\n    recipientPhone: 'your recipient phone number here',\n    latitude: 'your latitude here',\n    longitude: 'your longitude here',\n    name: 'your location name here',\n    address: 'your location street/address here',\n});\n```\n\n#### Send a document to a recipient:\n\n```js\n// Send a document that is hosted on a public URL\nawait Whatsapp.sendDocument({\n    recipientPhone: 'your recipient phone number here',\n    caption: 'Invoice #123.',\n    url: 'http://pdfkit.org/demo/out.pdf',\n});\n\n//OR\n\n// Send a document that is in your local filesystem (file will be uploaded to the WhatsApp server first before it is sent).\nawait Whatsapp.sendDocument({\n    recipientPhone: 'your recipient phone number here',\n    file_path: './output.pdf',\n    caption: 'Invoice #123',\n});\n```\n\n#### Send an image to a recipient\n\n```js\n// Send an image that is hosted on a public URL\nawait Whatsapp.sendImage({\n    recipientPhone: 'your recipient phone number here',\n    caption: 'Test',\n    file_path: 'https://example.com/image.png',\n});\n\n// OR\n\n// Send an image that is in your local filesystem (file will be uploaded to the WhatsApp server first before it is sent).\nawait Whatsapp.sendImage({\n    recipientPhone: 'your recipient phone number here',\n    caption: 'Test',\n    file_path: './XEIDF3D5FTBDF1.png',\n});\n```\n\n#### Send a video to a recipient\n\n```js\n// Send a video that is hosted on a public URL\nawait Whatsapp.sendVideo({\n    recipientPhone: 'your recipient phone number here',\n    caption: 'Test',\n    url: 'https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/720/Big_Buck_Bunny_720_10s_1MB.mp4',\n});\n\n// OR\n\n// Send a video that is in your local filesystem (file will be uploaded to the WhatsApp server first before it is sent).\nawait Whatsapp.sendVideo({\n    recipientPhone: 'your recipient phone number here',\n    caption: 'Test',\n    file_path: './last.mp4',\n});\n```\n\n#### Send an audio to a recipient\n\n```js\n// Send an audio that is hosted on a public URL\nawait Whatsapp.sendAudio({\n    recipientPhone: 'your recipient phone number here',\n    url: 'https://example.com/audio.mp3',\n});\n\n// OR\n\n// Send an audio that is in your local filesystem (file will be uploaded to the WhatsApp server first before it is sent).\nawait Whatsapp.sendAudio({\n    recipientPhone: 'your recipient phone number here',\n    caption: 'Test',\n    file_path: './last.mp3',\n});\n```\n\n#### Send a list of simple buttons to the recipient (max number of buttons allowed are 3)\n\n```js\nawait Whatsapp.sendSimpleButtons({\n    recipientPhone: 'your recipient phone number here',\n    message: `How may I help you today`,\n    listOfButtons: [\n        {\n            title: 'See some products',\n            id: 'see_categories',\n        },\n        {\n            title: 'Send my invoice',\n            id: 'print_invoice',\n        },\n        {\n            title: 'Talk to a human',\n            id: 'talk_to_human',\n        },\n    ],\n});\n```\n\n#### Send a list of radio buttons to a recipient: (max number of radio buttons allowed are 10)\n\n```js\nawait Whatsapp.sendRadioButtons({\n    recipientPhone: 'your recipient phone number here',\n    headerText: 'Black Friday Top 10 Products',\n    bodyText:\n        'Daggie has some great products lined up for you based on your previous shopping history.\\nPlease select one of the products below.',\n    footerText: 'Approved by Daggie Blanqx',\n    listOfSections: [\n        {\n            title: 'Top 3 Fashion',\n            rows: [\n                {\n                    title: 'Black LVX T-Shirt',\n                    description: 'KES 2999.00\\nLVX is a warm cotton t-shirt',\n                    id: 'SKU12_black_lvx_tshirt',\n                },\n                {\n                    title: 'Purple hoodie',\n                    description:\n                        'KES 1999.00\\nPurple hoodie with a Logrocket logo',\n                    id: 'SKU13_purple_hoodie',\n                },\n                {\n                    title: 'Air Jordan 1',\n                    description:\n                        'KES 10999.00\\nWe move where others do not.Wanna fly?',\n                    id: 'SKU14_air_jordan_1',\n                },\n            ],\n        },\n        {\n            title: 'Top 3 Gadgets',\n            rows: [\n                {\n                    title: 'Apple Watch',\n                    description:\n                        'KES 75999.00\\nTime is finite, enjoy every second of it',\n                    id: 'SKU15_apple_watch',\n                },\n                {\n                    title: 'Surface Pro',\n                    description: `KES 59999.00\\nDon't just surf the web, surf the world`,\n                    id: 'SKU16_surface_pro',\n                },\n                {\n                    title: 'Xiaomi Beats Speaker',\n                    description: `KES 45699\\nIt is in how your heartbeats, the way Xiaomi Beats.`,\n                    id: 'SKU17_xiaomi_beats_speaker',\n                },\n            ],\n        },\n        {\n            title: 'Top 3 Kitchen',\n            rows: [\n                {\n                    title: 'Portable Hand Mixer',\n                    description: `KES7899\\nTempt thy sweetbuds by mixing your favorite food uniformly.`,\n                    id: 'SKU18_portable_hand_mixer',\n                },\n                {\n                    title: 'Non-stick waffle-maker',\n                    description: `KES7899\\nGreat Waffles are made with the best ingredients.`,\n                    id: 'SKU19_non_stick_waffle_maker',\n                },\n                {\n                    title: '6-set Cooking Spoons',\n                    description: `KES7899\\nHold thy happiness right.`,\n                    id: 'SKU20_6_set_cooking_spoons',\n                },\n            ],\n        },\n        {\n            title: '1 random pick',\n            rows: [\n                {\n                    title: 'Nivea Icy Soap',\n                    description: `KES899\\nStay hydrated and refreshed. Nourish your skin.`,\n                    id: 'SKU21_nivea_icy_soap',\n                },\n            ],\n        },\n    ],\n});\n```\n\n#### Send a contact to a recipient:\n\n```js\nawait Whatsapp.sendContact({\n    recipientPhone: recipientPhone,\n    contact_profile: {\n        addresses: [\n            {\n                street: '1 Hacker Way',\n                city: 'Menlo Park',\n                state: 'CA',\n                zip: '94025',\n                country: 'United States',\n                country_code: 'us',\n                type: 'HOME',\n            },\n            {\n                street: '200 Jefferson Dr',\n                city: 'Menlo Park',\n                state: 'CA',\n                zip: '94025',\n                country: 'United States',\n                country_code: 'us',\n                type: 'WORK',\n            },\n        ],\n        birthday: '2002-02-14',\n        emails: [\n            {\n                email: 'test@fb.com',\n                type: 'WORK',\n            },\n            {\n                email: 'test@whatsapp.com',\n                type: 'HOME',\n            },\n        ],\n        name: {\n            formatted_name: 'Daggie Blanqx',\n            first_name: 'Daggie',\n            last_name: 'Blanqx',\n            middle_name: 'M.',\n            suffix: 'Sr',\n            prefix: 'Sw Engr',\n        },\n        org: {\n            company: 'WhatsApp',\n            department: 'Design',\n            title: 'Manager',\n        },\n        phones: [\n            {\n                phone: '+1 (940) 555-1234',\n                type: 'HOME',\n                wa_id: '16505551234', // optional\n            },\n            {\n                phone: '+1 (650) 555-1234',\n                type: 'WORK', // optional\n                wa_id: '16505551234', // optional\n            },\n        ],\n        urls: [\n            {\n                url: 'https://www.facebook.com',\n                type: 'WORK',\n            },\n            {\n                url: 'https://www.whatsapp.com',\n                type: 'HOME',\n            },\n        ],\n    },\n});\n```\n\n##### Generate a QR code which can be scanned by a recipient:\n\n```js\nlet result = await Whatsapp.createQRCodeMessage({\n    message: `Your QR code message here. I am a message hidden in a QR code.`,\n    imageType: 'png' || 'svg',\n});\n\nlet urlOfImage = result.data.qr_image_url;\n```\n\nSee the image below on how to display the QR code: \u003cbr/\u003e\n\u003cimg src=\"./static_files/XEIDF3D5FTBDF1.png\"\n    alt=\"Markdown Monster icon\"\n    style=\"height:250px;width:250px\" /\u003e\n\u003cbr/\u003e\n\n#### Mark a message as read:\n\n```js\nawait Whatsapp.markMessageAsRead({\n    message_id: 'the id of your message here',\n});\n// A non-retryable error will be thrown if the message is not found or a message that has already been read.\n```\n\n#### Limitations in outbound actions:\n\n-   The button id must be between 1 and 256 characters long.\n-   The button title must be between 1 and 20 characters long.\n-   The list of items is limited to 10.\n-   The description of items in list must be between 1 and 72 characters long.\n-   The title of the list must be between 1 and 24 characters long.\n-   The id of the list must be between 1 and 200 characters long.\n\n## Part 2: Inbound messages (From customers to business)\n\n#### Parse incoming messages:\n\n```js\n// req.body is the body of the request which ping the webhook. Invalid payloads will throw an error, and you should respond with HTTP status 5** or 4**, not 200.\n// remember to respond with HTTP 200 status at the end of a succesful inbound request.\nlet data = Whatsapp.parseMessage(req.body);\n/*\ndata.isMessage will be true if it is a message from a customer, it will be false otherwise.\ndata.isNotificationMessage will be true if it is a notification from a Meta(e.g a message delivery/read status notification), it will be false otherwise.\ndata will throw an error if the body of the webhook request is not valid or not from Meta.\n*/\n```\n\n#### Handling a _SIMPLE_ button click\n\n```js\nif (data?.isMessage) {\n    let incomingMessage = data.message;\n    let recipientPhone = incomingMessage.from.phone; // extract the phone number of the customer\n    let recipientName = incomingMessage.from.name; // extract the name of the customer\n    let typeOfMsg = incomingMessage.type; // extract the type of message\n    let message_id = incomingMessage.message_id; // extract the message id\n\n    if (typeOfMsg === 'simple_button_message') {\n        let button_id = incomingMessage.button_reply.id;\n        if (button_id === 'book_appointment') {\n\n            // The customer clicked on a simple button whose id is 'book_appointment'.\n            // You can respond to them with an outbound action eg, a text message\n            await Whatsapp.sendText({\n                message: `Hello customer, You clicked on the 'book appointment' button`,\n                recipientPhone: 'your recipient phone number here',\n            });\n        };\n    };\n```\n\n#### Handling a _RADIO_ button selection\n\n```js\nif (data?.isMessage) {\n    let incomingMessage = data.message;\n    let recipientPhone = incomingMessage.from.phone; // extract the phone number of the customer\n    let recipientName = incomingMessage.from.name; // extract the name of the customer\n    let typeOfMsg = incomingMessage.type; // extract the type of message\n    let message_id = incomingMessage.message_id; // extract the message id\n\n    if (typeOfMsg === 'radio_button_message') {\n        let selectionId = incomingMessage.list_reply.id;\n        if (selectionId === 'morning_session') {\n            // The customer selected the radio button whose id of 'morning_session'.\n            // You can respond to them with an outbound action eg, a text message\n            await Whatsapp.sendText({\n                message: `You have selected the 'morning_session' option`,\n                recipientPhone: 'your recipient phone number here'\n            });\n        };\n    };\n```\n\n### Help information\n\n-   If you have any questions, ask via the [GitHub Discussion forums](https://github.com/DaggieBlanqx/whatsappcloudapi_wrapper/discussions)\n-   If you have any suggestions or feedback, please [open an issue](https://github.com/DaggieBlanqx/whatsappcloudapi_wrapper/issues) or [create a pull request](https://github.com/DaggieBlanqx/whatsappcloudapi_wrapper/pulls).\n\n### Notes:\n\n-   This package is in active development.\n-   This means new features are added regularly.\n-   Incase your favorite feature is missing, you can always bump a version backwards or [create a pull request](https://github.com/DaggieBlanqx/whatsappcloudapi_wrapper/pulls) which will be reviewed and merged into [the next release](https://github.com/DaggieBlanqx/whatsappcloudapi_wrapper/releases).\n-   Thanks for your contribution.\n-   Happy coding!\n\n### Reach out:\n\n-   Follow me on Twitter: [@daggieblanqx](https://twitter.com/daggieblanqx)\n-   I am also on LinkedIn, where you can tag me to the awesome projects you've built using this package: [@daggieblanqx](https://www.linkedin.com/in/daggieblanqx/)\n-   Blog posts: [Logrocket/@Daggieblanqx](https://blog.logrocket.com/author/daggieblanqx/)\n\n```\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaggieblanqx%2Fwhatsappcloudapi_wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaggieblanqx%2Fwhatsappcloudapi_wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaggieblanqx%2Fwhatsappcloudapi_wrapper/lists"}