From afa2e20f623562f054218828566f7d7c6d89a121 Mon Sep 17 00:00:00 2001 From: Kalebu Date: Sun, 14 Aug 2022 16:02:05 +0300 Subject: [PATCH] updated the documentation --- README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 105 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 059fc0b..3af3fae 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ Unofficial python wrapper to [WhatsApp Cloud API](https://developers.facebook.co 3. Sending location 4. Sending interactive buttons 5. Sending template messages +6. Parsing messages and media received ## Getting started @@ -71,22 +72,16 @@ Here how you authenticate your application, you need to specify two things the ` Once you have authenticated your app, now you can start using the above mentioned feature as shown above; +> Apparently it is only possible to send messages other than templates after the target phone responds to an initial message. Reference: + ## Sending Messanges -Here how to send messages; +Use this method to send text message to a WhatsApp number. ```python >>> messenger.send_message('Your message ', 'Mobile eg: 255757xxxxx') ``` -### Example - -Here an example - -```python ->>> messenger.send_message('Hi there just testiing', '255757902132') -``` - ## Sending Images When 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. @@ -154,6 +149,8 @@ Here an example; Here an example; +> Note: row button title may not exceed 20 characters otherwise your message will not be sent to the target phone. + ```python >>> messenger.send_button( recipient_id="255757xxxxxx", @@ -185,6 +182,8 @@ Here an example; Here an example; +> 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. + ```python >>> messenger.send_reply_button( recipient_id="255757xxxxxx", @@ -217,7 +216,16 @@ Here an example; ## Sending a Template Messages -Here how to send a pre-approved template message; +Here how to send a pre-approved template message, Template messages can either be; + +1. Text template +2. Media based template +3. Interactive template + +You can customize the template message by passing a dictionary of components. + +You can find the available components in the documentation. + ```python >>> messenger.send_template("hello_world", "255757xxxxxx", components={}) @@ -227,9 +235,88 @@ Here how to send a pre-approved template message; Webhook 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. +Here an example on how you can use webhook to respond to incoming messages; + +```python + # Handle Webhook Subscriptions + data = request.get_json() + logging.info("Received webhook data: %s", data) + changed_field = messenger.changed_field(data) + if changed_field == "messages": + new_message = messenger.get_mobile(data) + if new_message: + mobile = messenger.get_mobile(data) + name = messenger.get_name(data) + message_type = messenger.get_message_type(data) + logging.info( + f"New Message; sender:{mobile} name:{name} type:{message_type}" + ) + if message_type == "text": + message = messenger.get_message(data) + name = messenger.get_name(data) + logging.info("Message: %s", message) + messenger.send_message(f"Hi {name}, nice to connect with you", mobile) + + elif message_type == "interactive": + message_response = messenger.get_interactive_response(data) + intractive_type = message_response.get("type") + message_id = message_response[intractive_type]["id"] + message_text = message_response[intractive_type]["title"] + logging.info(f"Interactive Message; {message_id}: {message_text}") + + elif message_type == "location": + message_location = messenger.get_location(data) + message_latitude = message_location["latitude"] + message_longitude = message_location["longitude"] + logging.info("Location: %s, %s", message_latitude, message_longitude) + + elif message_type == "image": + image = messenger.get_image(data) + image_id, mime_type = image["id"], image["mime_type"] + image_url = messenger.query_media_url(image_id) + image_filename = messenger.download_media(image_url, mime_type) + print(f"{mobile} sent image {image_filename}") + logging.info(f"{mobile} sent image {image_filename}") + + elif message_type == "video": + video = messenger.get_video(data) + video_id, mime_type = video["id"], video["mime_type"] + video_url = messenger.query_media_url(video_id) + video_filename = messenger.download_media(video_url, mime_type) + print(f"{mobile} sent video {video_filename}") + logging.info(f"{mobile} sent video {video_filename}") + + elif message_type == "audio": + audio = messenger.get_audio(data) + audio_id, mime_type = audio["id"], audio["mime_type"] + audio_url = messenger.query_media_url(audio_id) + audio_filename = messenger.download_media(audio_url, mime_type) + print(f"{mobile} sent audio {audio_filename}") + logging.info(f"{mobile} sent audio {audio_filename}") + + elif message_type == "file": + file = messenger.get_file(data) + file_id, mime_type = file["id"], file["mime_type"] + file_url = messenger.query_media_url(file_id) + file_filename = messenger.download_media(file_url, mime_type) + print(f"{mobile} sent file {file_filename}") + logging.info(f"{mobile} sent file {file_filename}") + else: + print(f"{mobile} sent {message_type} ") + print(data) + else: + delivery = messenger.get_delivery(data) + if delivery: + print(f"Message : {delivery}") + else: + print("No new message") + return "ok" +``` + Incase 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. -## steps +## steps to Deploy webhook to Heroku + 1. Click the deploy button and the Heroku webpage will open for authentication, after authentication sit back and relax for deployment to finish. [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/JAXPARROW/whatsapi-flask-webhook) @@ -238,6 +325,7 @@ Incase you want a hustle free automatic deployment of the webhook to the Heroku To 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). + ## Issues If 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; @@ -245,17 +333,18 @@ If you will face any issue with the usage of this package please raise one so as ## Contributing This is an opensource project under ```MIT License``` so any one is welcome to contribute from typo, to source code to documentation, ```JUST FORK IT```. - -## References + +## References + 1. [WhatsApp Cloud API official documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/) 2. [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) 3. [Meet Heyoo — an Open-source Python Wrapper for WhatsApp Cloud API](https://betterprogramming.pub/programming-whatsapp-is-now-even-easier-for-python-developers-e1a4343deed6) 4. [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) -## Related -1. [WhatsApp Cloud API PHP Wrapper ](https://github.com/pro-cms/whatsappcloud-php) -2. [Heyoo Javascript](https://github.com/JS-Hub-ZW/heyooh) +## Related +1. [WhatsApp Cloud API PHP Wrapper](https://github.com/pro-cms/whatsappcloud-php) +2. [Heyoo Javascript](https://github.com/JS-Hub-ZW/heyooh) ## All the credit