Metadata-Version: 2.3
Name: pynani
Version: 1.4.1
Summary: Open source python wrapper to Messenger API
Keywords: Messenger,wrapper,Meta,API,Facebook,Pynani
Author: Jorge Juárez
Author-email: Jorge Juárez <jorgeang33@gmail.com>
License: MIT License
         
         Copyright (c) 2024 Jorge Angel Juarez Vazquez
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Customer Service
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: colorlog>=6.10.1
Requires-Dist: requests>=2.33.1
Requires-Python: >=3.12, <4.0
Project-URL: Bug Tracker, https://github.com/jorge-jrzz/pynani/issues
Project-URL: Documentation, https://pynani-docs.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/jorge-jrzz/pynani
Description-Content-Type: text/markdown

<img align="center" src="https://raw.githubusercontent.com/jorge-jrzz/Pynani/main/docs/_static/banner-pynani-github.png" alt="banner Pynani">

---

Opensource python wrapper to Messenger API

## Features

### API

- Verify the webhook
- Send text messages
- Send attachments from a remote file (image, audio, video, file)
- Send attachments from a local file (image, audio, video, file)
- Send templates (generic, buttons, media, receipent)
- Send quick replies

### Other functionalities

- Get sender id
- Get type of message received
- Get text of the message received
- Get the url of the attachment received
- Get type of the attachment received
- Download attachments received

## Installation

Install Pynani with pip

```bash
  pip install pynani
```

Or install with pipenv (requires pipenv installed)

```bash
  pipenv install pynani
```

## Getting started

### Prerequisites

- **Python 3.8**+ installed
- To get started using this module, you will need **page access token** which you can get from the Facebook Developer Portal

### A simple echo bot

The Messenger class (defined in Messenger.py) encapsulates all API calls in a single class. It provides functions such as send_xyz (send_message, send_attachment etc.) and several ways to listen for incoming messages.

Create a file called echo_bot.py. Then, open the file and create an instance of the Messenger class.

```python
from pynani import Messenger

PAGE_ACCESS_TOKEN = 'EAAxxxxxxx...'
mess = Messenger(PAGE_ACCESS_TOKEN)
```

> [!IMPORTANT]
> Make sure to actually replace PAGE_ACCESS_TOKEN with your own page access token.

After that declaration, we need to register some message handlers. First, we need to create and verify a webhook with the help of _Flask_ or _FastAPI_.

```python
from flask import Flask, request, jsonify

app = Flask(__name__)

TOKEN = "abc123"

@app.get("/")
def meta_verify():
    return mess.verify_token(request.args, TOKEN)
```

Now let's define a webhook that handles certain messages

```python
@app.post("/")
def meta_webhook():
    data = request.get_json()
    sender_id = mess.get_sender_id(data)
    message = mess.get_message_text(data)
    if message == "Hello":
        mess.send_text_message(sender_id, "Hello, World!")
    if message == "Bye":
        mess.send_text_message(sender_id, "Nice to meet you! 👍🏽")

    return jsonify({"status": "success"}), 200
```

We now have a basic bot which replies a static message to "hello" and "bye" messages. To start the bot, add the following to our source file:

```python
if __name__ =='__main__':
    app.run(port=8080, debug=True)
```

Alright, that's it! Our source file now looks like this:

```python
from flask import Flask, request, jsonify
from pynani import Messenger

PAGE_ACCESS_TOKEN = 'EAAxxxxxxx...'
TOKEN = "abc123"

mess = Messenger(PAGE_ACCESS_TOKEN)
app = Flask(__name__)

@app.get("/")
def meta_verify():
    return mess.verify_token(request.args, TOKEN)

@app.post("/")
def meta_webhook():
    data = request.get_json()
    sender_id = mess.get_sender_id(data)
    message = mess.get_message_text(data)
    if message == "Hello":
        mess.send_text_message(sender_id, "Hello, World!")
    if message == "Bye":
        mess.send_text_message(sender_id, "Nice to meet you! 👍🏽")

    return jsonify({"status": "success"}), 200

if __name__ =='__main__':
    app.run(port=8080, debug=True)
```

To start the bot, simply open up a terminal and enter `python echo_bot.py` to run the bot! Test it by sending messages ("hello" and "bye").

## Related

Here are some related projects that I was inspired by them.

- [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI?tab=readme-ov-file)
- [WhatsApp Cloud API Wrapper](https://github.com/Neurotech-HQ/heyoo)
- [Messenger API Python](https://github.com/krishna2206/messenger-api-python)
