{"id":14986921,"url":"https://github.com/green-api/whatsapp-api-webhook-server-cpp","last_synced_at":"2025-04-11T23:11:11.225Z","repository":{"id":250858682,"uuid":"832002453","full_name":"green-api/whatsapp-api-webhook-server-cpp","owner":"green-api","description":"This library helps you easily create a С++ server endpoint to receive WhatsApp message webhooks.","archived":false,"fork":false,"pushed_at":"2025-03-01T16:29:52.000Z","size":196,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-25T19:01:36.373Z","etag":null,"topics":["whatsapp","whatsapp-api","whatsapp-bot","whatsapp-chat","whatsapp-chatbot","whatsapp-chatbot-cpp","whatsapp-cpp"],"latest_commit_sha":null,"homepage":"https://green-api.com/en","language":"C++","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/green-api.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}},"created_at":"2024-07-22T06:50:25.000Z","updated_at":"2025-02-11T11:57:57.000Z","dependencies_parsed_at":"2025-02-11T12:32:49.535Z","dependency_job_id":"87c39c4a-2a98-4c6a-8b60-1f026a9bc818","html_url":"https://github.com/green-api/whatsapp-api-webhook-server-cpp","commit_stats":{"total_commits":30,"total_committers":2,"mean_commits":15.0,"dds":"0.033333333333333326","last_synced_commit":"c2382d346e6d7dbbaa4b30847f57d8386d1272ef"},"previous_names":["green-api/whatsapp-api-webhook-server-cpp"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fwhatsapp-api-webhook-server-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fwhatsapp-api-webhook-server-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fwhatsapp-api-webhook-server-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fwhatsapp-api-webhook-server-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/green-api","download_url":"https://codeload.github.com/green-api/whatsapp-api-webhook-server-cpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248492868,"owners_count":21113163,"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":["whatsapp","whatsapp-api","whatsapp-bot","whatsapp-chat","whatsapp-chatbot","whatsapp-chatbot-cpp","whatsapp-cpp"],"created_at":"2024-09-24T14:13:47.707Z","updated_at":"2025-04-11T23:11:11.198Z","avatar_url":"https://github.com/green-api.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# whatsapp-api-webhook-server-cpp\r\n\r\n## Support links\r\n\r\n[![Support](https://img.shields.io/badge/support@green--api.com-D14836?style=for-the-badge\u0026logo=gmail\u0026logoColor=white)](mailto:support@green-api.com)\r\n[![Support](https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge\u0026logo=telegram\u0026logoColor=white)](https://t.me/greenapi_support_ru_bot)\r\n[![Support](https://img.shields.io/badge/WhatsApp-25D366?style=for-the-badge\u0026logo=whatsapp\u0026logoColor=white)](https://wa.me/447458038017)\r\n\r\n## Guides \u0026 News\r\n\r\n[![Guides](https://img.shields.io/badge/YouTube-%23FF0000.svg?style=for-the-badge\u0026logo=YouTube\u0026logoColor=white)](https://www.youtube.com/@greenapi-en)\r\n[![News](https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge\u0026logo=telegram\u0026logoColor=white)](https://t.me/green_api)\r\n[![News](https://img.shields.io/badge/WhatsApp-25D366?style=for-the-badge\u0026logo=whatsapp\u0026logoColor=white)](https://whatsapp.com/channel/0029VaLj6J4LNSa2B5Jx6s3h)\r\n\r\n- [Документация на русском языке](https://github.com/green-api/whatsapp-api-webhook-server-cpp/blob/master/README.ru.md).\r\n\r\n\r\n`whatsapp-api-webhook-server-cpp` — webhook server for integration with WhatsApp Messenger using the API service [green-api.com](https://green-api.com/). \r\nYou should get a registration token and an account ID in your [personal cabinet](https://console.green-api.com/). \r\nThere is a free developer account tariff.\r\n\r\n- [whatsapp-api-webhook-server-cpp](#whatsapp-api-webhook-server-cpp)\r\n  - [Support links](#support-links)\r\n  - [Guides \\\u0026 News](#guides--news)\r\n  - [API](#api)\r\n  - [Receiving Webhook Token](#receiving-webhook-token)\r\n  - [Building the app](#building-the-app)\r\n    - [Windows](#windows)\r\n    - [Linux](#linux)\r\n    - [Docker](#docker)\r\n  - [Running the app](#running-the-app)\r\n  - [User Adapter](#user-adapter)\r\n  - [Examples](#examples)\r\n  - [JSON Validation](#json-validation)\r\n  - [Webhooks documentation](#webhooks-documentation)\r\n  - [Library dependencies](#library-dependencies)\r\n  - [Licence](#licence)\r\n\r\n## API\r\n\r\nThe documentation for webhooks could be find [here](https://green-api.com/en/docs/api/#receiving). The app is a handler for it, so the documentation at the link above also applies.\r\n\r\n## Receiving Webhook Token\r\n\r\nTo receive a Webhook Token and be able to send requests into this server, the WhatsApp account in the phone app must be authorized. To authorize the account, go to your [cabinet](https://console.green-api.com/) and scan the QR code using the WhatsApp app.\r\n\r\n## Building the app\r\n\r\nThis app uses C++ 17, CMake 3.5, supports Linux (GCC) and Windows (Visual Studio 2019/2022) compilers.\r\n\r\nBefore building you should create this file (or copy existing one if you have it):\r\n\r\n- ```source/user_adapter.cpp```\r\n\r\nIf you don't have required file, create it by renaming with removing underscore from ```source/_user_adapter.cpp``` file.\r\n\r\nWe will update ```include/user_adapter.h``` and ```source/_user_adapter.cpp``` files as new webhooks are released. If you encountered build error, which tells compiler could not find required functions from ```user_adapter```, please add new functions from ```source/_user_adapter.cpp``` to yours ```source/user_adapter.cpp```.\r\n\r\n**This project will not build if you won't do it**.\r\n\r\n### Windows\r\n\r\nTo build the app you need:\r\n\r\n- [git](https://gitforwindows.org/) - a cross-platform utility used on this project for downloading libraries.\r\n\r\n- [CMake](https://cmake.org/download/) - a cross-platform utility for automatically building software from source code.\r\n\r\n- Compiler [Microsoft Visual C++ (MSVC)](https://visualstudio.microsoft.com/ru/downloads/) for C++ applications.\r\n\r\n\r\n```cmake``` and ```git``` must be accessible by PATH.\r\n\r\nBuilding is done by using the ```build.bat``` scenario (or ```.\\build.bat``` if Powershell used):\r\n\r\n```bash\r\ngit clone --branch=master --depth=1 https://github.com/green-api/whatsapp-api-webhook-server-cpp\r\ncd whatsapp-api-webhook-server-cpp\r\nbuild.bat\r\n```\r\n\r\nApplication is built at Release config by default. Config file ```config.json``` and directory ```jsonSchema``` are copied to ```build\\bin``` directory. The application prioritize ```build\\bin``` files over project's directory.\r\n\r\nAfter successful build you can build it using ```build.bat``` or \r\n\r\n```bash\r\ncmake --build build --config=Release\r\n```\r\n\r\nRun the application:\r\n\r\n```bash\r\nstart build\\bin\\whatsapp-api-webhook-server-cpp.exe\r\n```\r\n\r\nServer exposes port from ```config.json``` configuration (by default: ```5000```). Detailed configuration description available [here](#running-the-app).\r\n\r\n### Linux\r\n\r\nTo build the app you need git, g++, cmake:\r\n\r\n```bash\r\nsudo apt-get install git g++ cmake\r\n```\r\n\r\n```cmake``` and ```git``` must be accessible by bash.\r\n\r\nBuilding is done by using the ```build.sh``` scenario:\r\n\r\n```bash\r\ngit clone --branch=master --depth=1 https://github.com/green-api/whatsapp-api-webhook-server-cpp\r\ncd whatsapp-api-webhook-server-cpp\r\n.\\build.sh\r\n```\r\n\r\nApplication is built at Release config by default. Config file ```config.json``` and directory ```jsonSchema``` are copied to ```build/bin``` directory. The application will prioritize ```build/bin``` files over project's directory.\r\n\r\nAfter successful build you can build it using ```.\\build.sh``` or \r\n\r\n```bash\r\ncmake --build build --config=Release\r\n```\r\n\r\nRun the application:\r\n\r\n```bash\r\n./build/bin/whatsapp-api-webhook-server-cpp\r\n```\r\n\r\nServer exposes port from ```config.json``` configuration (by default: ```5000```). Detailed configuration description available [here](#running-the-app).\r\n\r\n### Docker\r\n\r\nTo run this project with Docker, you need Docker and Docker Compose.\r\n\r\nYou can install [Docker Desktop](https://www.docker.com/products/docker-desktop/) for all platforms or install [Docker Engine](https://docs.docker.com/engine/install/) for Linux.\r\n\r\nClone the repository:\r\n\r\n```bash\r\ngit clone --branch=master --depth=1 https://github.com/green-api/whatsapp-api-webhook-server-cpp\r\ncd whatsapp-api-webhook-server-cpp\r\n```\r\n\r\nBefore running Docker you should create this file (or copy existing one if you have it):\r\n\r\n- ```source/user_adapter.cpp```\r\n\r\nIf you don't have required file, create it by renaming with removing underscore from ```source/_user_adapter.cpp``` file.\r\n\r\nWe will update ```include/user_adapter.h``` and ```source/_user_adapter.cpp``` files as new webhooks are released. If you encountered build error, which tells compiler could not find required functions from ```user_adapter```, please add new functions from ```source/_user_adapter.cpp``` to yours ```source/user_adapter.cpp```.\r\n\r\nBy default, ```port 5000``` is exposed. If you would like to change it, you need:\r\n\r\n- Change ```Address``` field in ```config.json``` to your desired port;\r\n\r\n- Change ```ports``` field in ```docker-compose.yaml``` to your desired port;\r\n\r\nRun Docker image with Docker Compose. Use flag ```--build```, if you are running this container first time or project files have been changed:\r\n\r\n```bash\r\ndocker compose up --build\r\n```\r\n\r\nServer will be started after building automatically. Detailed configuration description available [here](#running-the-app).\r\n\r\n\r\n## Running the app\r\n\r\nThe application binary is placed in ```build/bin/```.\r\n\r\nThis project use ```config.json``` to set these variables:\r\n\r\n- Address (default: ```:5000```). Server will be launched on this port. Requests should be sent to this port. [Instance setup](https://green-api.com/en/docs/api/receiving/technology-webhook-endpoint/#webhookUrl);\r\n\r\n- Pattern (default: ```/```). Part of URI after port: \"Address\"\"Pattern\". All requests sent to wrong Pattern will be rejected. By default server will handle requests on URI = localhost:5000/. [Instance setup](https://green-api.com/en/docs/api/receiving/technology-webhook-endpoint/#webhookUrl);\r\n\r\n- WebhookToken (default: **none**). Authorization token, must be equal to a token declared in your green-api instance (none dy default). [Instance setup](https://green-api.com/en/docs/api/receiving/technology-webhook-endpoint/#webhookUrl);\r\n\r\n- LogToFile (default: ```false```). Defines the creation logger of a file and writing logs to it by program. Available values: true, false.\r\n\r\n- LogToConsole (default: ```false```). Defines writing logs into console by program. Available values: true, false.\r\n\r\n- LoggerFilename (default: ```log.txt```). Filename for logger's file.\r\n\r\nAfter starting the application, a server using values from config will be started. If no config exists, default values will be used.\r\n\r\nYou can use [Postman collection](https://green-api.com/en/docs/postman-collection/) for server testing.\r\n\r\n## User Adapter\r\n\r\nFor specifing user-defined functions when a notification received use ```user_adapter``` files. In these files you should define notifications handlers (for example: write notification into database, send request to other microservice). Template file ```source/_user_adapter.cpp``` can be used by it's renaming. Handler examples for all notification type are available in file ```user_adapter_example.cpp``` in directory ```examples```.\r\n\r\nThe user adapter located in:\r\n\r\n- ```sources/user_adapter.cpp```\r\n\r\nIf you don't have required file, create it by renaming with removing underscore from ```source/_user_adapter.cpp``` file.\r\n\r\nWe will update ```include/user_adapter.h``` and ```source/_user_adapter.cpp``` files as new webhooks are released. If you encountered build error, which tells compiler could not find required functions from ```user_adapter```, please add new functions from ```source/_user_adapter.cpp``` to yours ```source/user_adapter.cpp```.\r\n\r\nUser Adapter contains your handlers for incoming webhooks. It works according to the following algorithm:\r\n\r\n1. Request to the server is received by ```webhook``` class;\r\n\r\n2. ```webhook``` class creates ```Response``` object and transmits request body to the ```validator``` class;\r\n\r\n3. After validation, ```Response``` object transmits into ```UserAdapter``` handler, based on request's body ```webToken```;\r\n\r\n4. ```User Adapter``` function returns ```true``` if error or ```false``` if no error. Based on this value, server will return 200 OK or 400 Bad Request status.\r\n\r\nThe structure of ```Response``` object (response.h):\r\n\r\n```cpp\r\nstruct Response {\r\n    bool error = true; // true if incoming webhook failed to validate\r\n    std::string typeWebhook = \"\"; // webhookType taken from request body\r\n    std::string bodyStr = \"\";  // contains request body if error = false, otherwise contains validation error description\r\n    nlohmann::json bodyJson = \"\"; //  body of incoming request\r\n}\r\n```\r\n\r\n1. UserAdapter function defines as:\r\n```cpp\r\nstatic bool onWebhookType(greenapi::Response\u0026 body);\r\n```\r\n2. UserAdapter function example:\r\n\r\nIn this example, handler will be called by webhook with type ```IncomingMessageReceived```. Using the structure ```Response``` above, you could check for validate of request (```body.error```), work with webhook json structure (```body.bodyJson```) or get access to webhook raw body (```body.bodyStr```).\r\n\r\n```cpp\r\nbool UserAdapter::onIncomingMessageReceived(greenapi::Response\u0026 body) {\r\n    // Every request contains typeWebhook. Requests are rejected, if no typeWebhook given.\r\n    const auto typeWebhook = body.bodyJson[\"typeWebhook\"];\r\n\r\n    // If you encountered errors while hanlding, you should return true.\r\n    // It will change response status to 400 Bad Request with immediate return of the HTTP request result\r\n    // \r\n    // if (\u003cerror\u003e) {\r\n    //    return true;\r\n    //}\r\n\r\n    greenapi::Logger::Log(\"Received webhook: \" + nlohmann::to_string(typeWebhook) + std::string(\" with body: \") + body.bodyStr, \"info\");\r\n\r\n    // Write your handler here:\r\n\r\n    // Return false if no error, after this 200 OK response will be returned\r\n    return false;\r\n}\r\n```\r\n\r\n## Examples\r\n\r\nExamples are available in [user_adapter_example.cpp](./examples/user_adapter_example.cpp).\r\n\r\n## JSON Validation\r\n\r\nJSON schemas for webhooks validation are placed in ```jsonSchema``` directory and copied to build directory while running build script. You could add any ```.json``` files to ```build/bin/jsonSchema```, they will be loaded into a program while it starting.\r\n\r\nJSON schemas have this structure:\r\n\r\n```json\r\n{\r\n  \"$id\": \"schemas\",\r\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\r\n  \"type\": \"object\",\r\n  \"properties\": {\r\n    \"yourNameOfObject\": {\r\n      \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\r\n      \"type\": \"object\",\r\n      \"properties\": {\r\n        \"sampleField\": {\r\n          \"type\": \"string\"\r\n        },\r\n        \"sampleRef_Field\": {\r\n          \"$ref\": \"#/properties/commonSchemaComponents/properties/senderData\"\r\n        }\r\n      },\r\n      \"required\": [\r\n        \"typeWebhook\",\r\n      ],\r\n      \"additionalProperties\": true\r\n    },\r\n    \"yourOtherObject\": {\r\n        ...\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nTo make your ```.json``` file working, any ```.json``` file should contain only one object with ```\"properties\"```. All to-be-validated objects should be on ```\"properties\"``` object. Otherwise, your json file will be ignored.\r\n\r\n## Webhooks documentation\r\n\r\n[https://green-api.com/docs/api/](https://green-api.com/en/docs/api/receiving/notifications-format/).\r\n\r\n## Library dependencies\r\n\r\n- [poco](https://github.com/pocoproject/poco) — for HTTP server.\r\n- [nlohmann-json](https://github.com/nlohmann/json) — to work with JSON.\r\n- [json-schema-validator](https://github.com/pboettch/json-schema-validator) — for JSON validation.\r\n\r\n## Licence\r\n\r\nLicences under [\r\nCreative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)\r\n](https://creativecommons.org/licenses/by-nd/4.0/).\r\n[LICENSE](../LICENSE).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-api%2Fwhatsapp-api-webhook-server-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgreen-api%2Fwhatsapp-api-webhook-server-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-api%2Fwhatsapp-api-webhook-server-cpp/lists"}