Metadata-Version: 2.2
Name: pywce
Version: 1.0.1
Summary: A template-driven engine for building WhatsApp chatbots
Home-page: https://github.com/DonnC/pywce
Author: Donald Chinhuru
Author-email: donychinhuru@gmail.com
License: MIT
Project-URL: Bug Tracker, https://github.com/DonnC/pywce/issues
Project-URL: Source Code, https://github.com/DonnC/pywce
Project-URL: Documentation, https://docs.page/donnc/wce
Keywords: whatsapp,chatbot,yaml,automation,template,hooks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Chat
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: httpx~=0.28.1
Requires-Dist: cachetools~=5.5.0
Requires-Dist: ruamel.yaml~=0.18.10
Requires-Dist: requests-toolbelt~=1.0.0
Requires-Dist: Jinja2~=3.1.5
Requires-Dist: colorlog~=6.9.0
Requires-Dist: python-json-logger~=3.2.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Python WhatsApp ChatBot Engine

A library for creating WhatsApp chatbots using a template-driven approach. It decouples 
the engine from the WhatsApp client library, allowing developers to use them independently or 
together. 

Templates use YAML allowing you to define conversation flows and business logic in a clean and modular
way.

## Features

- **Template-Driven Design**: Use YAML templates for conversational flows.
- **Hooks for Business Logic**: Attach Python functions to process messages or actions.
- Easy-to-use API for WhatsApp Cloud.
- Supports dynamic messages with placeholders.
- Built-in support for WhatsApp Webhooks.


## Installation
```bash
pip install pywce
```


### WhatsApp Client Library

PyWCE provides a simple, Pythonic interface to interact with the WhatsApp Cloud API:

_**Note**: You can use pywce as a standalone whatsapp client library. See [FastApi Example](https://github.com/DonnC/pywce/blob/master/example/standalone_chatbot/main.py)_

- **Send messages** (text, media, templates, interactive)
- **Receive and process webhooks**
- **Media management** (upload and download)
- **Out of the box utilities** using the `WhatsApp.Utils` class.

Example usage:

```python
from pywce import WhatsAppConfig, WhatsApp

config = WhatsAppConfig(
    token="your_access_token",
    phone_number_id="your_phone_number_id",
    hub_verification_token="your_webhook_hub_verification_token"
)

whatsapp = WhatsApp(whatsapp_config=config)

# Sending a text message
response = whatsapp.send_message(
    recipient_id="recipient_number",
    message="Hello from PyWCE!"
)

# verify if request was successful, using utils
is_sent = whatsapp.util.was_request_successful(
    recipient_id="recipient_number",
    response_data=response
)

if is_sent:
    message_id = whatsapp.util.get_response_message_id(response)
    print("Request successful with msg id: ", message_id)
```

### Template Engine ChatBot

Here's a simple example template to get you started:

_**Note:** Checkout complete example chatbot with [Fast Api here](https://github.com/DonnC/pywce/blob/master/example/engine_chatbot/main.py)_

1. Define your YAML template:

```yaml
# path/to/templates
"START-MENU":
  type: button
  template: "example.hooks.name_template.username"
  message:
    title: Welcome
    body: "Hi {{ name }}, I'm your assistant, click below to start!"
    footer: pywce
    buttons:
      - Start
  routes:
    "start": "NEXT-STEP"
```

2. Write your hook:

```python
# example/hooks/name_template.py
from pywce import hook, HookArg, TemplateDynamicBody

@hook
def username(arg: HookArg) -> HookArg:
    # set render payload data to match the required template dynamic var
    arg.template_body = TemplateDynamicBody(
        render_template_payload={"name": arg.user.name}
    )

    return arg
```

3. Start the engine:

```python
from pywce import PywceEngine, PywceEngineConfig

config = PywceEngineConfig(
    templates_dir="path/to/templates",
    start_template_stage="START-MENU"
)
engine = PywceEngine(config=config)
```

## Documentation

Visit the [official documentation](https://docs.page/donnc/wce) for a detailed guide.

## Contributing

We welcome contributions! Please check out the [Contributing Guide](https://github.com/DonnC/pywce/blob/master/CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/DonnC/pywce/blob/master/LICENCE) file for details.
