{"id":14986955,"url":"https://github.com/neurotech-hq/heyoo","last_synced_at":"2025-05-14T14:08:16.634Z","repository":{"id":39657743,"uuid":"494442040","full_name":"Neurotech-HQ/heyoo","owner":"Neurotech-HQ","description":"Opensource  python wrapper to WhatsApp Cloud API","archived":false,"fork":false,"pushed_at":"2025-01-17T07:49:05.000Z","size":1903,"stargazers_count":483,"open_issues_count":22,"forks_count":107,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-05-13T16:57:40.591Z","etag":null,"topics":["python-whatsapp-cloud-api","whatsapp","whatsapp-api","whatsapp-business-api","whatsapp-cloud-api"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/heyoo/","language":"Python","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/Neurotech-HQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"patreon":"kalebujordan"}},"created_at":"2022-05-20T11:44:45.000Z","updated_at":"2025-05-13T15:59:06.000Z","dependencies_parsed_at":"2023-11-24T23:27:13.836Z","dependency_job_id":"d8ca9f8f-255b-4c65-8b1a-ab26e3cee3cc","html_url":"https://github.com/Neurotech-HQ/heyoo","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neurotech-HQ%2Fheyoo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neurotech-HQ%2Fheyoo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neurotech-HQ%2Fheyoo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neurotech-HQ%2Fheyoo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Neurotech-HQ","download_url":"https://codeload.github.com/Neurotech-HQ/heyoo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254160229,"owners_count":22024567,"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":["python-whatsapp-cloud-api","whatsapp","whatsapp-api","whatsapp-business-api","whatsapp-cloud-api"],"created_at":"2024-09-24T14:13:52.263Z","updated_at":"2025-05-14T14:08:16.608Z","avatar_url":"https://github.com/Neurotech-HQ.png","language":"Python","funding_links":["https://patreon.com/kalebujordan"],"categories":[],"sub_categories":[],"readme":"\u003csamp\u003e\n\n# [heyoo](https://pypi.org/project/heyoo/)\n\n[![Made in Tanzania](https://img.shields.io/badge/made%20in-tanzania-008751.svg?style=flat-square)](https://github.com/Tanzania-Developers-Community/made-in-tanzania)\n[![Downloads](https://static.pepy.tech/badge/heyoo)](https://pepy.tech/project/heyoo)\n[![Downloads](https://static.pepy.tech/badge/heyoo/month)](https://pepy.tech/project/heyoo)\n[![Downloads](https://static.pepy.tech/badge/heyoo/week)](https://pepy.tech/project/heyoo)\n\nUnofficial Python wrapper for the [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api)\n\n## Supported features\n\n1. Sending messages\n2. Marking messages as read\n3. Sending Media (images, audio, video and documents)\n4. Sending location\n5. Sending interactive buttons\n6. Sending template messages\n7. Parsing messages and media received\n\n## Getting started\n\nTo get started with **heyoo**, you have to firstly install the library either directly or using *pip*.\n\n### Building from source\n\nUse git to clone or you can also manually download the project repository just as shown below;\n\n```bash\n$ git clone https://github.com/Neurotech-HQ/heyoo\n$ cd heyoo\nheyoo $ python setup.py install \n```\n\n### Installing via pip\n\n```bash\n# For Windows \n\npip install  --upgrade heyoo\n\n#For Linux | MAC \n\npip3 install --upgrade heyoo\n```\n\n### Running on Docker\nTo run an instance in docker run the commands below\n```bash\n$ docker compose build\n$ docker compose up\n```\n\n## Setting up\n\nTo get started using this package, you will need **TOKEN** and **TEST WHATSAPP NUMBER** (the library works either with a production phone number, if you have one) which you can get from the [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 Business \u003e\u003e Business\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 **TOKEN** and **TEST WHATSAPP NUMBER** and its phone_number_id\n7. Lastly verify the number you will be using for testing on the **To** field.\n\nOnce you've followed the above procedures you're ready to start hacking with the Wrapper.\n\n## Authentication\n\nTo authenticate your application, you need to specify  the ```TOKEN``` and the ```phone_number_id``` of your application\n\n```python\n\u003e\u003e\u003e from heyoo import WhatsApp\n\u003e\u003e\u003e messenger = WhatsApp('TOKEN',  phone_number_id='104xxxxxx')\n```\n\nOnce you have authenticated your app you can start using the above mentioned feature as shown above;\n\n\u003e It is only possible to send messages other than templates only after the target phone responds to an initial template message or sends a message first. This resets every 24 hours; after that, you need to send a template again or the message won't be delivered. Reference: \u003chttps://developers.facebook.com/community/threads/425605939396247/\u003e\n\n## Logging\n\nYou can configure your own log level. This is an example to set the log level to info. By default only Error messages are logged.\n\n```python\nimport logging\n\nlogging.basicConfig(\n    level=logging.INFO,\n    format=\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\",\n)\n```\n\n## Sending Messanges\n\nUse this method to send text message to a WhatsApp number.\n\n```python\n\u003e\u003e\u003e await messenger.send_message('Your message ', 'Mobile eg: 255757xxxxx')\n```\n\n## Marking messages as read\n\nUse this method to mark a previously sent text message as read.\n\n```python\n\u003e\u003e\u003e await messenger.mark_as_read('Message ID')\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```python\n\u003e\u003e\u003e await messenger.send_image(\n        image=\"https://i.imgur.com/Fh7XVYY.jpeg\",\n        recipient_id=\"255757xxxxxx\",\n    )\n```\n\n\u003e Note: You can also send media from your local machine but you have to upload it first to Whatsapp Cloud API, you can do this using the ```upload_media``` method. and then use the returned object id to send the media.\n\nHere an example;\n\n```python\n\u003e\u003e\u003e media_id = await messenger.upload_media(\n        media='path/to/media',\n    )['id']\n\u003e\u003e\u003e await messenger.send_image(\n        image=media_id,\n        recipient_id=\"255757xxxxxx\",\n        link=False\n    )\n```\n\n\u003e Note: Don't forget to set the link to False, and also you can use the same technique for sending video, audio, gif and document from your local machine.\n\n## Sending Video\n\nHere an example;\n\n```python\n\n\u003e\u003e\u003e await messenger.send_video(\n        video=\"https://www.youtube.com/watch?v=K4TOrB7at0Y\",\n        recipient_id=\"255757xxxxxx\",\n    )\n```\n\n## Sending Audio\n\nHere an example;\n\n```python\n\u003e\u003e\u003e await messenger.send_audio(\n        audio=\"https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3\",\n        recipient_id=\"255757xxxxxx\",\n    )\n```\n\n## Sending Document\n\nHere an example;\n\n```python\n\u003e\u003e\u003e await messenger.send_document(\n        document=\"http://www.africau.edu/images/default/sample.pdf\",\n        recipient_id=\"255757xxxxxx\",\n    )\n```\n\n## Sending Location\n\nHere an example;\n\n```python\n\u003e\u003e\u003e await messenger.send_location(\n        lat=1.29,\n        long=103.85,\n        name=\"Singapore\",\n        address=\"Singapore\",\n        recipient_id=\"255757xxxxxx\",\n    )\n```\n\n## Sending Interactive buttons\n\nHere an example;\n\n\u003e Note: row button title may not exceed 20 characters otherwise your message will not be sent to the target phone.\n\n```python\n\u003e\u003e\u003e await messenger.send_button(\n        recipient_id=\"255757xxxxxx\",\n        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    )\n```\n\n## Sending Interactive reply buttons\n\nHere an example;\n\n\u003e Send reply button only displays three reply buttons, if it exceeds three reply buttons, it will raise an error and your message will not be sent.\n\n```python\n\u003e\u003e\u003e await messenger.send_reply_button(\n        recipient_id=\"255757xxxxxx\",\n        button={\n            \"type\": \"button\",\n            \"body\": {\n                \"text\": \"This is a test button\"\n            },\n            \"action\": {\n                \"buttons\": [\n                    {\n                        \"type\": \"reply\",\n                        \"reply\": {\n                            \"id\": \"b1\",\n                            \"title\": \"This is button 1\"\n                        }\n                    },\n                    {\n                        \"type\": \"reply\",\n                        \"reply\": {\n                            \"id\": \"b2\",\n                            \"title\": \"this is button 2\"\n                        }\n                    }\n                ]\n            }\n      },\n    )\n```\n\n## Sending a Template Messages\n  \nHere how to send a pre-approved template message, Template messages can either be;\n\n1. Text template\n2. Media based template\n3. Interactive template\n\nYou can customize the template message by passing a dictionary of components.\n\n    \nIMPORTANT: components are also known as variable parameters (like `{{0}}` or `{{1}}`) which are used to include variables into a message.\nYou can find the available components in the documentation.\n\u003chttps://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates\u003e\n\n```python\n\u003e\u003e\u003e await messenger.send_template(\"hello_world\", \"255757xxxxxx\", components=[], lang=\"en_US\")\n```\n`lang` is optional but required when sending templates in other languages.\n\n## Webhook\n\nWebhook 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/Neurotech-HQ/heyoo/blob/main/hook.py) which you can then customize it according to your own plans.\n\nHere an example on how you can use webhook to respond to incoming messages;\n\n```python\n  # Handle Webhook Subscriptions\n    data = request.get_json()\n    logging.info(\"Received webhook data: %s\", data)\n    changed_field = messenger.changed_field(data)\n    if changed_field == \"messages\":\n        new_message = messenger.get_mobile(data)\n        if new_message:\n            mobile = messenger.get_mobile(data)\n            name = messenger.get_name(data)\n            message_type = messenger.get_message_type(data)\n            logging.info(\n                f\"New Message; sender:{mobile} name:{name} type:{message_type}\"\n            )\n            if message_type == \"text\":\n                message = messenger.get_message(data)\n                name = messenger.get_name(data)\n                logging.info(\"Message: %s\", message)\n                await messenger.send_message(f\"Hi {name}, nice to connect with you\", mobile)\n\n            elif message_type == \"interactive\":\n                message_response = messenger.get_interactive_response(data)\n                interactive_type = message_response.get(\"type\")\n                message_id = message_response[interactive_type][\"id\"]\n                message_text = message_response[interactive_type][\"title\"]\n                logging.info(f\"Interactive Message; {message_id}: {message_text}\")\n\n            elif message_type == \"location\":\n                message_location = messenger.get_location(data)\n                message_latitude = message_location[\"latitude\"]\n                message_longitude = message_location[\"longitude\"]\n                logging.info(\"Location: %s, %s\", message_latitude, message_longitude)\n\n            elif message_type == \"image\":\n                image = messenger.get_image(data)\n                image_id, mime_type = image[\"id\"], image[\"mime_type\"]\n                image_url = await messenger.query_media_url(image_id)\n                image_filename = await messenger.download_media(image_url, mime_type)\n                print(f\"{mobile} sent image {image_filename}\")\n                logging.info(f\"{mobile} sent image {image_filename}\")\n\n            elif message_type == \"video\":\n                video = messenger.get_video(data)\n                video_id, mime_type = video[\"id\"], video[\"mime_type\"]\n                video_url = await messenger.query_media_url(video_id)\n                video_filename = await messenger.download_media(video_url, mime_type)\n                print(f\"{mobile} sent video {video_filename}\")\n                logging.info(f\"{mobile} sent video {video_filename}\")\n\n            elif message_type == \"audio\":\n                audio = messenger.get_audio(data)\n                audio_id, mime_type = audio[\"id\"], audio[\"mime_type\"]\n                audio_url = await messenger.query_media_url(audio_id)\n                audio_filename = await messenger.download_media(audio_url, mime_type)\n                print(f\"{mobile} sent audio {audio_filename}\")\n                logging.info(f\"{mobile} sent audio {audio_filename}\")\n\n            elif message_type == \"document\":\n                file = messenger.get_document(data)\n                file_id, mime_type = file[\"id\"], file[\"mime_type\"]\n                file_url = await messenger.query_media_url(file_id)\n                file_filename = await messenger.download_media(file_url, mime_type)\n                print(f\"{mobile} sent file {file_filename}\")\n                logging.info(f\"{mobile} sent file {file_filename}\")\n            else:\n                print(f\"{mobile} sent {message_type} \")\n                print(data)\n        else:\n            delivery = messenger.get_delivery(data)\n            if delivery:\n                print(f\"Message : {delivery}\")\n            else:\n                print(\"No new message\")\n    return \"ok\"\n```\n\nIncase you want a hustle free automatic deployment of the webhook to the Heroku platform, then we have made it simpler for you. With Just a click of a button you can deploy your webhook to Heroku.\n\n## steps to Deploy webhook to Heroku\n\n1. Click the deploy button and the Heroku webpage will open for authentication, after authentication sit back and relax for deployment to finish.\n                             [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/JAXPARROW/whatsapi-flask-webhook)\n\n2. From Heroku settings configure your Environment varibles of your WhatsAapp application.\n3. Setup and verify your webhook url and token then subscribe to messages.\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## 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 or documentation, ```JUST FORK IT```.\n\n## References\n\n1. [WhatsApp Cloud API official documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/)\n2. [Programming WhatsApp is now even easier for Python Developers](https://mr-collins-llb.medium.com/programming-whatsapp-is-now-even-easier-for-python-developers-e1a4343deed6)\n3. [Meet Heyoo — an Open-source Python Wrapper for WhatsApp Cloud API](https://betterprogramming.pub/programming-whatsapp-is-now-even-easier-for-python-developers-e1a4343deed6)\n4. [Whatsapp Cloud API: How to send WhatsApp messages from Python?](https://medium.com/@today.rafi/whatsapp-cloud-api-how-to-send-whatsapp-messages-from-python-9baa03c93b5d)\n\n## Related\n\n1. [WhatsApp Cloud API PHP Wrapper](https://github.com/pro-cms/whatsappcloud-php)\n2. [Heyoo Javascript](https://github.com/JS-Hub-ZW/heyooh)\n\n## All the credit\n\n1. [kalebu](https://github.com/Kalebu)\n2. All other contributors\n\u003c/samp\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneurotech-hq%2Fheyoo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneurotech-hq%2Fheyoo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneurotech-hq%2Fheyoo/lists"}